# HG changeset patch # User Ludovic Chabant # Date 1443970963 25200 # Node ID 3a61f45702cb1bc5975c8c0de2834a591b6d9fbc # Parent d5511d832af30b76fc833313ddf7daca1d0d7251 docs: Add documentation site. diff -r d5511d832af3 -r 3a61f45702cb .hgignore --- a/.hgignore Sun Oct 04 08:01:18 2015 -0700 +++ b/.hgignore Sun Oct 04 08:02:43 2015 -0700 @@ -9,9 +9,14 @@ *.pyo *.sublime-* MANIFEST +.eggs/ Wikked.egg-info benchmarks/Benchmark.conf benchmarks/logs benchmarks/logs-distributed benchmarks/results +docs/_cache +docs/_counter +docs/bower_components +docs/node_modules diff -r d5511d832af3 -r 3a61f45702cb docs/assets/css/wikked.less --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/assets/css/wikked.less Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,125 @@ +// Import Pure. +@import (less) "../../bower_components/pure/pure.css"; + +// Import Font-Awesome. +@import "../../bower_components/font-awesome/less/font-awesome.less"; + +// Import stuff from the wikked package. +@wikked-path: "../../../wikked/assets/css"; + +// Import basic variables and mixins. +@import "@{wikked-path}/wikked/base.less"; + +// Now import our styles. +@import "@{wikked-path}/wikked/nav.less"; +@import "@{wikked-path}/wikked/main.less"; +@import "@{wikked-path}/wikked/page.less"; + +// Code sections. +.highlight pre { + color: @code-color; + background: @code-bg; + padding: 1em 0.5em; +} + +// Quotes with a nice icon. +blockquote { + padding: 1em; + margin: 1em 0; + min-height: 220px; + color: lighten(@color-gray-dark, 3%); + background: darken(@color-gray-light, 5%); + + p { + margin-left: 170px; // width/height of the "toto" image: 145x200 + } + p:first-child::before { + content: " "; + background-image: url('../img/toto.png'); + background-repeat: no-repeat; + background-position: left center; + display: block; + float: left; + margin-left: -170px; + margin-top: -1em; + width: 150px; + height: 220px; + } +} + +// Make room for the home shortcut. +// (it's different from the wiki shortcut) +.wrapper.wiki-docs { + padding-top: @wiki-shortcut-width !important; + padding-left: 0 !important; +} +#wiki-menu ul:first-child { + margin-top: 3.8em; +} + +// Collapse by default +#wiki-menu { + left: -@wiki-menu-width !important; +} + +// TODO: remove this by using the same version of PureCSS. +#wiki-menu li a { + .wiki-menu-a(); + display: block; + line-height: 1.5em; + + &:hover { + .wiki-menu-a-hover(); + } +} + +// Docs want wider articles. +.wiki-docs article, +.wiki-docs header { + max-width: 1024px; + margin: 0 auto; + padding: 0 1em; +} + +// Big headers. +.wiki-docs header h1 { + font-size: 3em; +} +.wiki-docs header.header-bg { + background-repeat: no-repeat; + background-position: center center; + background-size: cover; + margin-top: -@wiki-shortcut-width; + margin-bottom: 2em; + padding: 8em 2em 1em 3.5em; + max-width: 100%; + + h1 { + color: #fff; + } +} + +@media screen and (min-width: 48em) { + // Visible menu by default on big screens. + .wrapper.wiki-docs { + padding-top: 0 !important; + padding-left: @wiki-menu-width !important; + } + #wiki-menu { + left: 0 !important; + } + + .wiki-docs article, + .wiki-docs header { + padding: 0 2em; + } + + .wiki-docs header h1 { + font-size: 4em; + } + + .wiki-docs header.header-bg { + padding-top: 10em; + padding-left: 4.5em; + } +} diff -r d5511d832af3 -r 3a61f45702cb docs/assets/fonts/FontAwesome.otf Binary file docs/assets/fonts/FontAwesome.otf has changed diff -r d5511d832af3 -r 3a61f45702cb docs/assets/fonts/fontawesome-webfont.eot Binary file docs/assets/fonts/fontawesome-webfont.eot has changed diff -r d5511d832af3 -r 3a61f45702cb docs/assets/fonts/fontawesome-webfont.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/assets/fonts/fontawesome-webfont.svg Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,640 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff -r d5511d832af3 -r 3a61f45702cb docs/assets/fonts/fontawesome-webfont.ttf Binary file docs/assets/fonts/fontawesome-webfont.ttf has changed diff -r d5511d832af3 -r 3a61f45702cb docs/assets/fonts/fontawesome-webfont.woff Binary file docs/assets/fonts/fontawesome-webfont.woff has changed diff -r d5511d832af3 -r 3a61f45702cb docs/assets/fonts/fontawesome-webfont.woff2 Binary file docs/assets/fonts/fontawesome-webfont.woff2 has changed diff -r d5511d832af3 -r 3a61f45702cb docs/assets/humans.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/assets/humans.txt Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,14 @@ +# humanstxt.org/ +# The humans responsible & technology colophon + +# AUTHORS + +Ludovic Chabant -- @ludovicchabant + +# TECHNOLOGY + +PieCrust -- http://bolt80.com/piecrust + +# THANKS + + diff -r d5511d832af3 -r 3a61f45702cb docs/assets/img/toto.png Binary file docs/assets/img/toto.png has changed diff -r d5511d832af3 -r 3a61f45702cb docs/assets/js/wikked.js.concat --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/assets/js/wikked.js.concat Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,5 @@ +path_mode: absolute +files: + - bower_components/jquery/dist/jquery.js + - assets/js/wikked/app.js + diff -r d5511d832af3 -r 3a61f45702cb docs/assets/js/wikked/app.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/assets/js/wikked/app.js Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,7 @@ +$(document).ready(function() { + $('#wiki-menu-shortcut').click(function() { + $('.wrapper').toggleClass('wiki-menu-active'); + $('#wiki-menu').toggleClass('wiki-menu-active'); + }); +}); + diff -r d5511d832af3 -r 3a61f45702cb docs/assets/robots.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/assets/robots.txt Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,6 @@ +# www.robotstxt.org/ + +# Allow crawling of all content +User-agent: * +Disallow: + diff -r d5511d832af3 -r 3a61f45702cb docs/bower.json --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/bower.json Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,9 @@ +{ + "name": "Wikked", + "version": "0.0.1", + "private": "true", + "dependencies": { + "pure": "~0.6.0", + "font-awesome": "~4.4.0" + } +} diff -r d5511d832af3 -r 3a61f45702cb docs/config.yml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/config.yml Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,13 @@ +site: + title: Wikked + sources: + pages: + type: ordered + +markdown: + extensions: abbr, fenced_code, footnotes, smart_strong, codehilite, smarty + extension_configs: + codehilite: + css_class: highlight + guess_lang: false + diff -r d5511d832af3 -r 3a61f45702cb docs/pages/00__index.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/pages/00__index.md Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,43 @@ +--- +title: Wikked +icon: home +--- + +**Wikked** is a [wiki][] engine that stores its data in plain text files using +a common revision control system like [Mercurial][] or [Git][]. It's mostly +suitable for an individual, family, or small team. + +The source code is available on [Github][] and [BitBucket][]. + +## Quickstart + +Install **Wikked** using Python 3.4 or later and `pip`: + + pip install wikked + +Let's create a new wiki: + + wk init mywiki + +This will create a new directory called `mywiki` with some basic files in it. It +will also initialize a [Mercurial][] repository in it. + +Now let's get in there and run it: + + cd mywiki + wk runserver + +You should now be able to open your favorite web browser and go to +`localhost:5000`. If you see the main page of your wiki, congratulations! +Otherwise, something went wrong. If you found a bug make sure to [file a +report][1] about it. + + +[wiki]: https://en.wikipedia.org/wiki/Wiki +[git]: http://git-scm.com/ +[mercurial]: http://mercurial.selenic.com/ +[github]: https://github.com/ludovicchabant/Wikked +[bitbucket]: https://bitbucket.org/ludovicchabant/wikked +[1]: https://github.com/ludovicchabant/Wikked/issues + + diff -r d5511d832af3 -r 3a61f45702cb docs/pages/01_installation.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/pages/01_installation.md Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,48 @@ +--- +title: Installation +icon: cloud-download +--- + +## From the package index + +You need [Python 3.4][py3] or later to use Wikked. Then, the easiest way to +install it is to use `pip`: + + pip install wikked + +If you want to use the very latest (and potentially broken) version: + + pip install git+ssh://git@github.com/ludovicchabant/Wikked.git#egg=Wikked + +Check that you have Wikked correctly installed by running: + + wk --help + +You should see Wikked's command line help. + +## From source + +You can also use Wikked from source. It's recommended that you use `virtualenv` +for this (see the [documentation][venv] for more info). It would look something +like this: + + # Clone with either Mercurial or Git: + hg clone ssh://hg@bitbucket.org/ludovicchabant/wikked + git clone git@github.com:ludovicchabant/Wikked.git + + # Create and activate virtualenv, if you're on Bash + virtualenv venv + source venv/bin/activate + + # Install Wikked's requirements in venv + pip install -r requirements.txt + + python wk.py --help + +Just remember to activate your virtual environment every time you open a new +console. + +[py3]: https://www.python.org/downloads/ +[venv]: http://www.virtualenv.org/ + + diff -r d5511d832af3 -r 3a61f45702cb docs/pages/02_overview.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/pages/02_overview.md Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,87 @@ +--- +title: Overview +icon: book +--- + +Wikked's data is entirely stored in text files on disk. All you ever need, or +should really care about, are those text files, and the source control +repository which contains their history. Wikked may create some other files -- +cache files, indices, etc. -- but they can always be safely deleted and +re-created. + + +## The wiki folder + +If you look at your new wiki, you should see a file called `Main page.md`, along +with a few hidden files and directories. + +* Each page's text is stored in a file whose name is the name of the page -- + like that `Main page.md`. That name is important, since that's what you'll use + for linking to it, and what will show up in that page's URL. A page named + `Toto.md` would be available at the URL `/read/Toto`. + +* Sub-directories also map to sub-folders in page names and URLs, so a file + located at `Villains/Flying monkeys.md` would be available at + `/read/Villains/Flying monkeys.md`. + +* There's a `.wiki` folder that was created in the wiki root. This folder is + a cache, and can generally be safely deleted and re-created with the `wk + reset` command. You may however have some [local configuration + file(s)][config] in there, which we'll talk about later, so watch out before + deleting that folder. + +* There's also some source control related files in there, like a `.hg` folder + and `.hgignore` file in the case of Mercurial. Don't touch those, they're + important (they store your pages' history). You can learn about them using the + wonders of the internet. + +> There's nothing preventing you from using accented or non-latin characters for +> a new page name, except for characters that would be invalid for a file name. +> However, please note that most revision control systems are going to behave +> badly if you'll be working with your repository on mixed systems (_i.e._ +> Windows, Mac, Linux). + + +## General features + +Wikked implements the usual wiki concepts of being able to edit pages, look at +their history and revert to previous revisions, and of course easily link to +other pages. + +Wikked also supports the ability to include a page into another page, to assign +metadata (like categories) to pages, and to query pages based on that metadata. +So for example you can display a list of all pages under the category "_Witches +of Oz_". + + +## Limitations + +Wikked was written mainly for a small group of editors in mind. It's especially +well suited for a personal digital notebook, a private family documents +repository, or a wiki for a small team of people. + +The main limitation of Wikked comes into play when you increase the number of +contributors -- *not* when you increase the number of visitors. Once the website +is cached, all requests are done against the SQL database, and search is done +through the indexer. This means you can scale quite well as long as you have the +appropriate backend (and as long as I don't write anything stupid in the code). + +However, user accounts are stored in a text file, and must be added by hand by +an administrator, so it's impossible to scale this up to hundreds or thousands +of users. You could probably improve this by adding a different user account +backend, but when those users start editing pages, each edit must write to a +separate file on disk, and be committed to a source control repository, and this +will probably prove to be a bottleneck anyway at some point. + +In summary: Wikked should be able to handle lots of visitors, but not too +many contributors. + +## Support + +If you need assistance with Wikked, [contact me directly][me] or report an issue +on the [GitHub bug tracker][bugs]. + + [me]: http://ludovic.chabant.com + [bugs]: https://github.com/ludovicchabant/Wikked/issues + [config]: {{pcurl('configuration')}} + diff -r d5511d832af3 -r 3a61f45702cb docs/pages/03_configuration.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/pages/03_configuration.md Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,111 @@ +--- +title: Configuration +icon: cog +--- + +Wikked can be configured with a few files: + +* `.wikirc`: this file, located at the root of your wiki, can be submitted into + revision control, so that various clones of the wiki have the same options + where it makes sense. + +* `.wiki/wikirc`: some options, however, don't have to be the same depending on + where you run the wiki. This file is contained in the ignored-by-default + `.wiki` folder, and as such is meant to store options valid only for a local + installation. + +* `.wiki/app.cfg`: Wikked runs on top of [Flask][]. This file, if it exists, + will be passed on to Flask for more advanced configuration scenarios. See the + [Flask configuration documentation][1] for more information. + + [flask]: http://flask.pocoo.org/ + [1]: http://flask.pocoo.org/docs/0.10/config/ + + +The `wikirc` file is meant to be written with an INI-style format: + +``` +[section1] +foo=bar +something=some other value + +[section2] +blah=whatever +``` + + +## Main options + +The main Wikked options should be defined in a `[wiki]` section. Here are the +supported options: + +* `main_page` (defaults to `Main page`): the name of the page that should be + displayed when people visit the root URL of your wiki. Page names are case + sensitive so watch out for the capitalization. + +* `templates_dir` (defaults to `Templates`): by default, the `include` statement + (see the [syntax page][2]) will first look into a templates directory for + a template of the given name. This is the name of that folder. + +* `indexer` (defaults to `whoosh`): The full-text indexer to use. Only 2 indexers are currently + supported, `whoosh` (for [Whoosh][]) and `elastic` (for [Elastic Search][elastic]). + +* `database` (defaults to `sql`): The database system to use for the cache. + Wikked currently only supports SQL, but see the next option below. + +* `database_url` (defaults to `sqlite:///%(root)s/.wiki/wiki.db`): the URL to + pass to [SQLAlchemy][] for connecting to the database. As you can see, the + default value will read or create an [SQLite][] file in the `.wiki` folder. If + you want to use a proper SQL server you can specify its URL and login + information instead. See the [SQLAlchemy connection string format][3] for more + information. + + [2]: {{pcurl('syntax')}} + [3]: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls + [SQLite]: http://sqlite.org + [SQLAlchemy]: http://sqlalchemy.org + [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home + [elastic]: http://www.elasticsearch.org/ + + +## Permissions + +The `wikirc` file can also be used to define user permissions. This is done with +the `[users]` section: + + [users] + dorothy=PASSWORD_HASH + +The `PASSWORD_HASH` is, well, a password hash. You can generate one by using the +`wk newuser` command: + + $ wkdev newuser dorothy + Password: ******** + dorothy = $2a$12$7FR949jt9zq5iNwY5WAZAOzD7pK3P0f/NnrKHAys17HT1Omuk2Asu + + (copy this into your .wikirc file) + +Once you have some users defined, you can give them some permissions, using the +`[permissions]` section. Supported settings are: + +* `readers`: users able to read the wiki. +* `writers`: users able to edit the wiki. + +Multiple usernames must be separated by a comma. You can also use `*` for "all +users", and `anonymous` for unauthenticated visitors. + +The following example shows a wiki only accessible to registered users, and that +can only be edited by `dorothy` and `toto`: + + [permissions] + readers = * + writers = dorothy,toto + +Those settings can also be overriden at the page level using the `readers` and +`writers` metadata. So you can still have a public landing page for the +previously mentioned private wiki by adding this to `Main page.md`: + + {%raw%} + {{readers: *,anonymous}} + {%endraw%} + diff -r d5511d832af3 -r 3a61f45702cb docs/pages/04_syntax.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/pages/04_syntax.md Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,252 @@ +--- +title: Syntax +icon: pencil +--- + +## Formatting + +By default, Wikked will use [Markdown][] syntax, so that things like these: + + Ring around the rosie, a pocket full of *spears*! Thought you were pretty + foxy, didn't you? **Well!** The last to go will see the first three go + before her! _And your mangy little dog, too!_ + +...turn into this: + +> Ring around the rosie, a pocket full of *spears*! Thought you were pretty +> foxy, didn't you? **Well!** The last to go will see the first three go +> before her! _And your mangy little dog, too!_ + +[markdown]: http://daringfireball.net/projects/markdown/ + +Page files that have a `.md` extension will be formatted using Markdown. Other +formats can be used, like Textile, by using other extensions. + + +## Links + +Wikked uses a simple wiki link syntax: + +* Links are made with double square brackets: `[[Flying monkeys]]` will link to a + page called `Flying monkeys.md`. + +* Linking respects the "current directory", _i.e._ the directory of the current + page. Linking to `Flying monkeys` from `Villains/Wicked Witch` will lead + you to `Villains/Flying monkeys`. + +* To link using an "absolute" path, start with a slash: `[[/Villains/Flying + monkeys]]` will work regardless of the page you're currently writing it into. + This is for instance useful for templates. + +* To link to a page in the parent directory, use `..` like so: + `[[../Munchkins]]`. + +* You can quickly link to "child" pages by using `./`. For example, if you have + a page called `/Munchkins` that links to `[[./Lollipop Guild]]`, it will lead + to the page `/Munchkins/Lollipop Guild`. + +* To give a different display name, write it before a vertical bar: `[[click + here|Flying monkeys]]`. + + +## Metadata + +To assign metadata to a page, use `{%raw%}{{name: value}}{%endraw%}`. For instance: + + {%raw%} + {{category: Witches}} + {%endraw%} + +You may need to assign a long value, like the summary of the page, which you may +not want to write all in one single line. In that case, you can use multiple +lines, but you need to put the closing double curly braces by themselves on the +last line: + + {%raw%} + {{summary: This page is about flying monkeys, who serve + the wicked witch of the west. They're not very bright + but they are extremely loyal. + }} + {%endraw%} + +> Note that the carriage return to get to the closing braces won't be included +> in the metadata. If you want the metadata value to end with a carriage return, +> you'll need to add one, effectively leaving an empty line before the closing +> braces. + +Finally, you can also set a metadata without any value if the point is just to +metaphorically flip a switch on the page. Just leave the value empty: + + {%raw%} + {{is_villain: }} + {%endraw%} + + +### Well-know metadata + +Although most metadata you'll use will be for you only, some of it is used to +tell Wikked to do something special. + +* `category`: Adds the current page to the given category. You can specify this + metadata multiple times to make the page part of multiple categories. The + Wikked UI will show the categories of a page at the bottom. + +* `notitle`: If specified, the Wikked UI won't show the title of this page. This + lets you use a banner graphic or some other way to present the page to + a visitor. + +* `redirect`: Redirects to another page. + +* `readers`: Specifies the users who can read this page. When not present, the + default readers for the wiki will be able to read the page. See the + [configuration page][1] for more information. + +* `writers`: Similar to the previous metadata, but for the ability to edit + a page. + + + +## Includes + +The metadata syntax is also used for including and querying pages. For instance, +to include the `Warning` page in another page: + + {%raw%} + {{include: Warning}} + {%endraw%} + +You can supply a relative or absolute page name to the `include` meta. For +convenience, however, Wikked will first look in the `/Templates` folder for a +page of that name to include. If it doesn't find one, it will resolve the path +as usual. + +> You can make Wikked look into a different folder than `/Templates` by changing +> the `templates_dir` option in the configuration file. See the [configuration +> documentation][1] for more information. + +The `include` metadata accepts arguments. For example, the `City of Oz` +page may have this at the top: + + {%raw%} + {{include: Warning + |a work in progress + |adding references + }} + {%endraw%} + +Those arguments can then be used by the included `/Templates/Warning` page: + + {%raw%} + WARNING! This page is {{__args[0]}}. + You can help by {{__args[1]}}. + {%endraw%} + +This will make `City of Oz` print the following warning: + + WARNING! This page is a work in progress. + You can help by adding references. + +As you can see, arguments are passed as an array named `__args`, and this can be +inserted using double curly brackets. So {%raw%}`{{__args[0]}}`{%endraw%} +inserts the first passed argument, {%raw%}`{{__args[1]}}`{%endraw%} inserts the +second, and so on. + +You can also pass arguments by name: + + {%raw%} + {{include: Presentation + |what=dog + |nickname=Toto + }} + {%endraw%} + +And use them by name in the included template: + + {%raw%} + My {{what}} is called {{nickname}}. + {%endraw%} + +In reality, when included, a page's text will be processed through [Jinja2][] +templating so you can also use all kinds of fancy logic. For example, if you +want to support a default warning message, and an optional information message, +you can rewrite the `/Template/Warning` page like so: + + {%raw%} + WARNING! This page is {{__args[0]|default('not ready')}}. + {%if __args[1]%}You can help by {{__args[1]}}.{%endif%} + {%endraw%} + +For more information about what you can do, refer to the [Jinja2 templating +documentation][jinja2_tpl]. + + [jinja2]: http://jinja.pocoo.org/ + [jinja2_tpl]: http://jinja.pocoo.org/docs/templates/ + +Pages with other pages included in them inherit the meta properties of the +included pages. You can tweak that behaviour: + +* Meta properties that start with `__` (double underscore) will be "local" or + "private" to that page, _i.e._ they won't be inherited by pages including the + current one. +* Meta properties that start with `+` (plus sign) will only be "added" or + "given" to pages including the current one, _i.e._ the current page won't have + that property, but pages including it will. + + +## Queries + +The query metadata takes the name and value of another metadata to query on +pages. So for instance you can display a list of pages in the "_Witches_" +category like so: + + {%raw%} + {{query: category=Witches}} + {%endraw%} + +This will print a bullet list of the matching pages' titles, with a link to +each. + +You can customize how the list looks like by setting the following arguments: + +* `__header`: The text to print before the list. The default is an empty line. +* `__item`: The text to print for each matching page. It defaults to: `* + {%raw%}[[{{title}}|{{url}}]]{%endraw%}` (which means, as per Markdown + formatting, that it will print a bulleted list of titles linking to each + page). +* `__footer`: The text to print after the list. The default is an empty line. +* `__empty`: The text to show when no pages match the query. It defaults to a + simple text saying that no page matched the query. + +So for example, to display a description of each page next to its link, where +the description is taken from a `description` metadata on each matching page, +you would do: + + {%raw%} + {{query: category=Witches + |__item=* [[{{title}}|{{url}}]]: {{description}} + + }} + {%endraw%} + +Note the extra empty line so that each item has a line return at the end... +otherwise, they would be all printed on the same line! + +When a query parameter gets too complicated, you can store it in a separate +metadata property, as long as that property starts with a double underscore: + + {%raw%} + {{__queryitem: * [[{{title}}|{{url}}]]: {{description}} }} + + {{query: category=Witches|__item=__queryitem}} + {%endraw%} + +For extra long item templates, you can use a dedicated page. For example, here's +how you use the text in `/Templates/Witches Item` as the query item template: + + {%raw%} + {{query: category=Witches|__item=[[/Templates/Witches Item]]}} + {%endraw%} + + +[1]: {{pcurl('configuration')}} + diff -r d5511d832af3 -r 3a61f45702cb docs/pages/05_deployment.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/pages/05_deployment.md Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,136 @@ +--- +title: Deployment +icon: server +--- + +Wikked runs by default with an "easy" configuration, _i.e._ something that will +"just work" when you play around locally. In this default setup, it uses +[SQLite][] for the cache, and [Whoosh][] for the full-text search, all running +in Flask's built-in server. + + [whoosh]: https://bitbucket.org/mchaput/whoosh/wiki/Home + [sqlite]: https://sqlite.org/ + +This technology stack works very well for running your wiki locally, or for +private websites. It has some limitations, however: + +* The `wk runserver` command runs the Flask development server, which you + [shouldn't use in production][flaskdeploy]. You'll probably need to run Wikked + inside a proper server instead. +* When a page has been edited, Wikked will immediately evaluate and reformat all + pages that have a dependency on it. You probably want to have this done in the + background instead. + +In this chapter we'll therefore look at deployment options, and follow-up with +some more advanced configurations for those with special requirements. + + [flaskdeploy]: http://flask.pocoo.org/docs/deploying/ + + +## Apache and WSGI + +A simple way to run Wikked on a production server is to use [Apache][] with +[`mod_wsgi`][wsgi]. For a proper introduction to the matter, you can see +[Flask's documentation on the subject][flask_wsgi]. Otherwise, you can probably +reuse the following examples. + + [apache]: https://httpd.apache.org/ + [wsgi]: http://code.google.com/p/modwsgi/ + [flask_wsgi]: http://flask.pocoo.org/docs/deploying/mod_wsgi/ + +The first thing is to create a `.wsgi` file somewhere on your server. You only +need to create the Wikked WSGI app in it, and optionally activate your +`virtualenv` if you're using that: + + # Activate your virtualenv + activate_this = '/path/to/venv/bin/activate_this.py' + execfile(activate_this, dict(__file__=activate_this)) + + # Get the Wikked WSGI app + from wikked.wsgiutil import get_wsgi_app + application = get_wsgi_app('/path/to/your/wiki/root') + +The second thing to do is to add a new virtual host to your Apache +configuration. The [Flask documentation][flask_wsgi] shows an example that you +should be able to use directly, although you'll also need to tell Apache where +to serve some static files: Wikked's static files (Javascript, CSS, icons, +etc.), and your own wiki's files (your pictures and other attachments). This +means your Apache configuration will look like this in the end: + + + ServerName yourwikidomain.com + + WSGIDaemonProcess yourwiki user=user1 group=group1 threads=5 + WSGIScriptAlias / /path/to/your/wsgi/file.wsgi + + DocumentRoot /path/to/your/wiki/_files + Alias /static/ /path/to/wikked/static/ + + + WSGIProcessGroup yourwiki + WSGIApplicationGroup %{GLOBAL} + Order deny,allow + Allow from all + + + +> You will have to create the `_files` directory in your wiki before +> reloading Apache, otherwise it may complain about it. +> +> Also, the path to Wikked's `static` directory is going to point directly into +> your installed Wikked package. So if you installed it with `virtualenv`, it +> would be something like: +> `/path/to/your/wiki/venv/lib/python/site-packages/wikked/static`. + + +## Background updates + +The second thing to do is to enable background wiki updates. Good news: they're +already enabled if you used the `get_wsgi_app` function from the previous +section (you can disable it by passing `async_update=False` if you really need +to). + +> If you want to use background updates locally, you can do `wk runserver +> --usetasks`. + +However, you'll still need to run a separate process that, well, runs those +updates in the background. To do this: + + cd /path/to/my/wiki + wk runtasks + +> The background task handling is done with [Celery][]. By default, Wikked will +> use the [SQLAlchemy transport][celerysqlite]. + + [celery]: http://www.celeryproject.org/ + [celerysqlite]: http://docs.celeryproject.org/en/latest/getting-started/brokers/sqlalchemy.html + + +## Backend options + +**This is for advanced use only** + +If you want to use a different storage than SQLite, set the `database_url` +setting in your `wikirc` to an [SQLAlchemy-supported database URL][SQLAlchemy]. +For instance, if you're using MySQL with `pymsql` installed: + + [wiki] + database_url=mysql+pymysql://username:password123@localhost/db_name + + [sqlalchemy]: http://docs.sqlalchemy.org/en/rel_0_9/core/engines.html#database-urls + +> Note that you'll have to install the appropriate SQL layer. For instance: `pip +> install pymsql`. You will also obviously need to setup and configure your SQL +> server. + + +If Whoosh is also not suited to your needs, you can use [Elastic +Search][elastic] instead: + + [wiki] + indexer=elastic + +You'll obviously have to install and run Elastic Search. + + [elastic]: http://www.elasticsearch.org/ + diff -r d5511d832af3 -r 3a61f45702cb docs/templates/default.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/default.html Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,51 @@ +{% import "google.html" as google %} + + + + + + + + + + {% if page.title %}{{ page.title }} — {% endif %}Wikked + + + {% block head %}{% endblock %} + + +
+
+ {% include 'inc/nav.html' %} +
+
+ {% block header %} + {% if page.header_bg %} +
+

{{page.title}}

+
+ {% else %} +
+

{{ page.title }}

+
+ {% endif %} + {% endblock %} + {% block content %} +
+ {{content|safe}} +
+ {% endblock %} +
+
+ {% include 'inc/footer.html' %} +
+
+ + {{ piecrust.debug_info|safe }} + {% if baker and baker.is_baking %} + {{ google.analytics("UA-3426592-10") }} + {% endif %} + + diff -r d5511d832af3 -r 3a61f45702cb docs/templates/google.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/google.html Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,33 @@ +{% macro webfonts(fontnames) %} + +{% endmacro %} + +{% macro analytics(siteId) %} + +{% endmacro %} + +{% macro adsense(client, name, slot, width, height) %} + + +{% endmacro %} + diff -r d5511d832af3 -r 3a61f45702cb docs/templates/inc/footer.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/inc/footer.html Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,6 @@ + + diff -r d5511d832af3 -r 3a61f45702cb docs/templates/inc/nav.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/templates/inc/nav.html Sun Oct 04 08:02:43 2015 -0700 @@ -0,0 +1,17 @@ + + +