Mercurial > wikked

annotate docs/pages/03_configuration.md @ 394:dbe7dde07e85

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
runserver: Fix wiki updater not being set properly. The wiki updater was set but subsequently overwritten in the `runserver` command along with all the wiki factory params. Now we store them on the settings objects for the app to pick up on creation.
author Ludovic Chabant <ludovic@chabant.com>
date Wed, 14 Oct 2015 22:58:00 -0700
parents c19b8cc11938
children dcaa41b39c23
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Configuration
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 icon: cog
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4 ---
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6 Wikked can be configured with a few files:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 * `.wikirc`: this file, located at the root of your wiki, can be submitted into
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 revision control, so that various clones of the wiki have the same options
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 where it makes sense.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12 * `.wiki/wikirc`: some options, however, don't have to be the same depending on
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13 where you run the wiki. This file is contained in the ignored-by-default
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
14 `.wiki` folder, and as such is meant to store options valid only for a local
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15 installation.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
16
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17 * `.wiki/app.cfg`: Wikked runs on top of [Flask][]. This file, if it exists,
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 will be passed on to Flask for more advanced configuration scenarios. See the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
19 [Flask configuration documentation][1] for more information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
20
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21 [flask]: http://flask.pocoo.org/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 [1]: http://flask.pocoo.org/docs/0.10/config/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
24
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
25 The `wikirc` file is meant to be written with an INI-style format:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
27 ```
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28 [section1]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29 foo=bar
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 something=some other value
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32 [section2]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 blah=whatever
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 ```
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
36
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
37 ## Main options
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 The main Wikked options should be defined in a `[wiki]` section. Here are the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 supported options:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
41
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42 * `main_page` (defaults to `Main page`): the name of the page that should be
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 displayed when people visit the root URL of your wiki. Page names are case
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 sensitive so watch out for the capitalization.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45
383
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
46 * `default_extension` (defaults to `md`): the file extension (and therefore
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
47 formatting engine) to use by default when creating a new page. The default
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
48 values is `md` for [Markdown][].
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
49
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 * `templates_dir` (defaults to `Templates`): by default, the `include` statement
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51 (see the [syntax page][2]) will first look into a templates directory for
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 a template of the given name. This is the name of that folder.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54 * `indexer` (defaults to `whoosh`): The full-text indexer to use. Only 2 indexers are currently
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55 supported, `whoosh` (for [Whoosh][]) and `elastic` (for [Elastic Search][elastic]).
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
56
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
57 * `database` (defaults to `sql`): The database system to use for the cache.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58 Wikked currently only supports SQL, but see the next option below.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
59
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60 * `database_url` (defaults to `sqlite:///%(root)s/.wiki/wiki.db`): the URL to
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 pass to [SQLAlchemy][] for connecting to the database. As you can see, the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62 default value will read or create an [SQLite][] file in the `.wiki` folder. If
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63 you want to use a proper SQL server you can specify its URL and login
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64 information instead. See the [SQLAlchemy connection string format][3] for more
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65 information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67 [2]: {{pcurl('syntax')}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68 [3]: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69 [SQLite]: http://sqlite.org
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70 [SQLAlchemy]: http://sqlalchemy.org
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71 [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72 [elastic]: http://www.elasticsearch.org/
383
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
73 [markdown]: http://daringfireball.net/projects/markdown/
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
75
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
76 ## Permissions
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78 The `wikirc` file can also be used to define user permissions. This is done with
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79 the `[users]` section:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81 [users]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82 dorothy=PASSWORD_HASH
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
83
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
84 The `PASSWORD_HASH` is, well, a password hash. You can generate one by using the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
85 `wk newuser` command:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
86
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
87 $ wkdev newuser dorothy
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
88 Password: ********
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
89 dorothy = $2a$12$7FR949jt9zq5iNwY5WAZAOzD7pK3P0f/NnrKHAys17HT1Omuk2Asu
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
90
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
91 (copy this into your .wikirc file)
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
92
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
93 Once you have some users defined, you can give them some permissions, using the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
94 `[permissions]` section. Supported settings are:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
95
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
96 * `readers`: users able to read the wiki.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
97 * `writers`: users able to edit the wiki.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
98
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
99 Multiple usernames must be separated by a comma. You can also use `*` for "all
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
100 users", and `anonymous` for unauthenticated visitors.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
101
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
102 The following example shows a wiki only accessible to registered users, and that
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
103 can only be edited by `dorothy` and `toto`:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
104
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
105 [permissions]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
106 readers = *
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
107 writers = dorothy,toto
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
108
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
109 Those settings can also be overriden at the page level using the `readers` and
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
110 `writers` metadata. So you can still have a public landing page for the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
111 previously mentioned private wiki by adding this to `Main page.md`:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
112
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
113 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
114 {{readers: *,anonymous}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
115 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
116
383
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
117
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
118 ## Ignored files
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
119
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
120 The optional `ignore` section lets you define files or folders for Wikked to
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
121 ignore (_i.e._ files that are not pages, or folder that don't contain pages).
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
122
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
123 Each item in this section should be `name = pattern`, where `name` is irrelevant,
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
124 and `pattern` is a glob-like pattern:
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
125
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
126 [ignore]
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
127 venv = venv
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
128 temp = *~
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
129 temp2 = *.swp
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
130
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
131 This will ignore a `venv` folder or file at the root, or any file or folder
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
132 anywhere that ends with `~` or `.swp`.
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
133
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
134