Mercurial > wikked

annotate docs/pages/03_configuration.md @ 435:d8a1a031ad7d 0.7.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cm: Make invoke tasks work with the new version of invoke.
author Ludovic Chabant <ludovic@chabant.com>
date Thu, 30 Mar 2017 20:14:31 -0700
parents 0f4032dafc1f
children
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
398
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
4 header_img: witch.png
382
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
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
7 Wikked can be configured with a few files:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 * `.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
10 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
11 where it makes sense.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12
398
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
13 * `.wiki/wikirc`: some options may have to be different depending on where you
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
14 run the wiki from. This file is a complementary variant of the `.wikirc` file,
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
15 but is contained in the ignored-by-default `.wiki` folder. As such it is meant
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
16 to store options valid only for a local installation.
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
17
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
18 * `.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
19 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
20 [Flask configuration documentation][1] for more information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
21
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
22 [flask]: http://flask.pocoo.org/
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
23 [1]: http://flask.pocoo.org/docs/0.10/config/
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
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
26 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
27
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
28 ```
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
29 [section1]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
30 foo=bar
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
31 something=some other value
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33 [section2]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 blah=whatever
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
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38 ## Main options
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 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
41 supported options:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
42
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 * `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
44 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
45 sensitive so watch out for the capitalization.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46
383
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
47 * `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
48 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
49 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
50
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51 * `templates_dir` (defaults to `Templates`): by default, the `include` statement
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 (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
53 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
54
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55 * `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
56 supported, `whoosh` (for [Whoosh][]) and `elastic` (for [Elastic Search][elastic]).
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
57
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58 * `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
59 Wikked currently only supports SQL, but see the next option below.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 * `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
62 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
63 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
64 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
65 information instead. See the [SQLAlchemy connection string format][3] for more
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66 information.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68 [2]: {{pcurl('syntax')}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69 [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
70 [SQLite]: http://sqlite.org
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71 [SQLAlchemy]: http://sqlalchemy.org
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72 [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73 [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
74 [markdown]: http://daringfireball.net/projects/markdown/
382
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
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77 ## Permissions
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79 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
80 the `[users]` section:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82 [users]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
83 dorothy=PASSWORD_HASH
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
84
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
85 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
86 `wk newuser` command:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
87
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
88 $ wkdev newuser dorothy
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
89 Password: ********
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
90 dorothy = $2a$12$7FR949jt9zq5iNwY5WAZAOzD7pK3P0f/NnrKHAys17HT1Omuk2Asu
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
91
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
92 (copy this into your .wikirc file)
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
93
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
94 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
95 `[permissions]` section. Supported settings are:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
96
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
97 * `readers`: users able to read the wiki.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
98 * `writers`: users able to edit the wiki.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
99
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
100 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
101 users", and `anonymous` for unauthenticated visitors.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
102
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
103 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
104 can only be edited by `dorothy` and `toto`:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
105
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
106 [permissions]
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
107 readers = *
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
108 writers = dorothy,toto
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
109
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
110 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
111 `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
112 previously mentioned private wiki by adding this to `Main page.md`:
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
113
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
114 {%raw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
115 {{readers: *,anonymous}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
116 {%endraw%}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
117
383
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
118
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
119 ## Ignored files
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
120
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
121 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
122 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
123
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
124 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
125 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
126
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
127 [ignore]
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
128 venv = venv
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
129 temp = *~
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
130 temp2 = *.swp
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
131
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
132 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
133 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
134
c19b8cc11938 docs: Add information about the `ignore` section, and more wiki options.
Ludovic Chabant <ludovic@chabant.com>
parents: 382
diff changeset
135