Mercurial > wikked

comparison docs/pages/03_configuration.md @ 382:3a61f45702cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Add documentation site.
author Ludovic Chabant <ludovic@chabant.com>
date Sun, 04 Oct 2015 08:02:43 -0700
parents
children c19b8cc11938
comparison
equal deleted inserted replaced
381:d5511d832af3 382:3a61f45702cb
1 ---
2 title: Configuration
3 icon: cog
4 ---
5
6 Wikked can be configured with a few files:
7
8 * `.wikirc`: this file, located at the root of your wiki, can be submitted into
9 revision control, so that various clones of the wiki have the same options
10 where it makes sense.
11
12 * `.wiki/wikirc`: some options, however, don't have to be the same depending on
13 where you run the wiki. This file is contained in the ignored-by-default
14 `.wiki` folder, and as such is meant to store options valid only for a local
15 installation.
16
17 * `.wiki/app.cfg`: Wikked runs on top of [Flask][]. This file, if it exists,
18 will be passed on to Flask for more advanced configuration scenarios. See the
19 [Flask configuration documentation][1] for more information.
20
21 [flask]: http://flask.pocoo.org/
22 [1]: http://flask.pocoo.org/docs/0.10/config/
23
24
25 The `wikirc` file is meant to be written with an INI-style format:
26
27 ```
28 [section1]
29 foo=bar
30 something=some other value
31
32 [section2]
33 blah=whatever
34 ```
35
36
37 ## Main options
38
39 The main Wikked options should be defined in a `[wiki]` section. Here are the
40 supported options:
41
42 * `main_page` (defaults to `Main page`): the name of the page that should be
43 displayed when people visit the root URL of your wiki. Page names are case
44 sensitive so watch out for the capitalization.
45
46 * `templates_dir` (defaults to `Templates`): by default, the `include` statement
47 (see the [syntax page][2]) will first look into a templates directory for
48 a template of the given name. This is the name of that folder.
49
50 * `indexer` (defaults to `whoosh`): The full-text indexer to use. Only 2 indexers are currently
51 supported, `whoosh` (for [Whoosh][]) and `elastic` (for [Elastic Search][elastic]).
52
53 * `database` (defaults to `sql`): The database system to use for the cache.
54 Wikked currently only supports SQL, but see the next option below.
55
56 * `database_url` (defaults to `sqlite:///%(root)s/.wiki/wiki.db`): the URL to
57 pass to [SQLAlchemy][] for connecting to the database. As you can see, the
58 default value will read or create an [SQLite][] file in the `.wiki` folder. If
59 you want to use a proper SQL server you can specify its URL and login
60 information instead. See the [SQLAlchemy connection string format][3] for more
61 information.
62
63 [2]: {{pcurl('syntax')}}
64 [3]: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
65 [SQLite]: http://sqlite.org
66 [SQLAlchemy]: http://sqlalchemy.org
67 [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home
68 [elastic]: http://www.elasticsearch.org/
69
70
71 ## Permissions
72
73 The `wikirc` file can also be used to define user permissions. This is done with
74 the `[users]` section:
75
76 [users]
77 dorothy=PASSWORD_HASH
78
79 The `PASSWORD_HASH` is, well, a password hash. You can generate one by using the
80 `wk newuser` command:
81
82 $ wkdev newuser dorothy
83 Password: ********
84 dorothy = $2a$12$7FR949jt9zq5iNwY5WAZAOzD7pK3P0f/NnrKHAys17HT1Omuk2Asu
85
86 (copy this into your .wikirc file)
87
88 Once you have some users defined, you can give them some permissions, using the
89 `[permissions]` section. Supported settings are:
90
91 * `readers`: users able to read the wiki.
92 * `writers`: users able to edit the wiki.
93
94 Multiple usernames must be separated by a comma. You can also use `*` for "all
95 users", and `anonymous` for unauthenticated visitors.
96
97 The following example shows a wiki only accessible to registered users, and that
98 can only be edited by `dorothy` and `toto`:
99
100 [permissions]
101 readers = *
102 writers = dorothy,toto
103
104 Those settings can also be overriden at the page level using the `readers` and
105 `writers` metadata. So you can still have a public landing page for the
106 previously mentioned private wiki by adding this to `Main page.md`:
107
108 {%raw%}
109 {{readers: *,anonymous}}
110 {%endraw%}
111