# HG changeset patch # User Ludovic Chabant # Date 1539752931 25200 # Node ID bba13de7a7d16a96d20ff1bc1a88e18067ce23e4 # Parent 771225b80f18be5e4a24099f1649d77b23163f3d docs: Remove documentation, it's now on a wiki at `wikked.bolt80.com`. diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/css/wikked.less --- a/docs/assets/css/wikked.less Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,138 +0,0 @@ -// 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-img-width: 72px + 20px; -@blockquote-img-height: 100px + 20px; - -blockquote { - padding: 1em; - margin: 1em 0; - min-height: @blockquote-img-height; - color: lighten(@color-gray-dark, 3%); - background: darken(@color-gray-light, 5%); - - p { - margin-left: @blockquote-img-width; // width/height of the "toto" image: 72x100 - } - 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: -@blockquote-img-width; - margin-top: -1em; - width: @blockquote-img-width; - height: @blockquote-img-height; - } -} - -// 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; - } -} - -.wiki-docs header.header-img { - img { margin: 1em; float: right; } - h1 { float: left; } - &::after { - content: " "; - display: block; - clear: both; - } -} - -@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 771225b80f18 -r bba13de7a7d1 docs/assets/fonts/FontAwesome.otf Binary file docs/assets/fonts/FontAwesome.otf has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/fonts/fontawesome-webfont.eot Binary file docs/assets/fonts/fontawesome-webfont.eot has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/fonts/fontawesome-webfont.svg --- a/docs/assets/fonts/fontawesome-webfont.svg Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,640 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/fonts/fontawesome-webfont.ttf Binary file docs/assets/fonts/fontawesome-webfont.ttf has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/fonts/fontawesome-webfont.woff Binary file docs/assets/fonts/fontawesome-webfont.woff has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/fonts/fontawesome-webfont.woff2 Binary file docs/assets/fonts/fontawesome-webfont.woff2 has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/humans.txt --- a/docs/assets/humans.txt Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ -# humanstxt.org/ -# The humans responsible & technology colophon - -# AUTHORS - -Ludovic Chabant -- @ludovicchabant - -# TECHNOLOGY - -PieCrust -- http://bolt80.com/piecrust - -# THANKS - - diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/dead_witch.png Binary file docs/assets/img/dead_witch.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/melting.png Binary file docs/assets/img/melting.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/monkey.png Binary file docs/assets/img/monkey.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/soldier_monkey.png Binary file docs/assets/img/soldier_monkey.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/toto.png Binary file docs/assets/img/toto.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/witch.png Binary file docs/assets/img/witch.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/img/wizard.png Binary file docs/assets/img/wizard.png has changed diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/js/wikked.js.concat --- a/docs/assets/js/wikked.js.concat Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -path_mode: absolute -files: - - bower_components/jquery/dist/jquery.js - - assets/js/wikked/app.js - diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/js/wikked/app.js --- a/docs/assets/js/wikked/app.js Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,7 +0,0 @@ -$(document).ready(function() { - $('#wiki-menu-shortcut').click(function() { - $('.wrapper').toggleClass('wiki-menu-active'); - $('#wiki-menu').toggleClass('wiki-menu-active'); - }); -}); - diff -r 771225b80f18 -r bba13de7a7d1 docs/assets/robots.txt --- a/docs/assets/robots.txt Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ -# www.robotstxt.org/ - -# Allow crawling of all content -User-agent: * -Disallow: - diff -r 771225b80f18 -r bba13de7a7d1 docs/bower.json --- a/docs/bower.json Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,10 +0,0 @@ -{ - "name": "Wikked", - "version": "0.0.1", - "private": "true", - "dependencies": { - "pure": "~0.6.0", - "font-awesome": "~4.4.0", - "jquery": "~2.1.4" - } -} diff -r 771225b80f18 -r bba13de7a7d1 docs/config.yml --- a/docs/config.yml Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,20 +0,0 @@ -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 - -variants: - dist: - baker: - assets_dirs: - assets: - processors: all - diff -r 771225b80f18 -r bba13de7a7d1 docs/pages/00__index.md --- a/docs/pages/00__index.md Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,44 +0,0 @@ ---- -title: Wikked -icon: home -header_img: dead_witch.png ---- - -**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 --pre 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 771225b80f18 -r bba13de7a7d1 docs/pages/01_installation.md --- a/docs/pages/01_installation.md Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,49 +0,0 @@ ---- -title: Installation -icon: cloud-download -header_img: monkey.png ---- - -## 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 --pre 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 771225b80f18 -r bba13de7a7d1 docs/pages/02_overview.md --- a/docs/pages/02_overview.md Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,94 +0,0 @@ ---- -title: Overview -icon: book -header_img: melting.png ---- - -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. - - -## General features - -Wikked implements the usual [wiki][] concepts of being able to edit pages, look -at their history, revert to previous revisions, or 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_". - -Finally, because the wiki sits on top of a standard source controlled -repository with text files in it, you can edit, pull, push, merge, rebase, and -more. This may not be shown correctly on the web history page, but you can still -do that. - -[wiki]: https://en.wikipedia.org/wiki/Wiki - - -## 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). - - -## 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 771225b80f18 -r bba13de7a7d1 docs/pages/03_configuration.md --- a/docs/pages/03_configuration.md Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,135 +0,0 @@ ---- -title: Configuration -icon: cog -header_img: witch.png ---- - -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 may have to be different depending on where you - run the wiki from. This file is a complementary variant of the `.wikirc` file, - but is contained in the ignored-by-default `.wiki` folder. As such it 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. - -* `default_extension` (defaults to `md`): the file extension (and therefore - formatting engine) to use by default when creating a new page. The default - values is `md` for [Markdown][]. - -* `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/ - [markdown]: http://daringfireball.net/projects/markdown/ - - -## 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%} - - -## Ignored files - -The optional `ignore` section lets you define files or folders for Wikked to -ignore (_i.e._ files that are not pages, or folder that don't contain pages). - -Each item in this section should be `name = pattern`, where `name` is irrelevant, -and `pattern` is a glob-like pattern: - - [ignore] - venv = venv - temp = *~ - temp2 = *.swp - -This will ignore a `venv` folder or file at the root, or any file or folder -anywhere that ends with `~` or `.swp`. - - diff -r 771225b80f18 -r bba13de7a7d1 docs/pages/04_syntax.md --- a/docs/pages/04_syntax.md Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,254 +0,0 @@ ---- -title: Syntax -icon: pencil -header_img: soldier_monkey.png ---- - -## 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. The link resolution rules apply to the - redirect target. - -* `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 -- link -resolving rules apply. For convenience, however, if the path is not absolute, -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 771225b80f18 -r bba13de7a7d1 docs/pages/05_deployment.md --- a/docs/pages/05_deployment.md Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,140 +0,0 @@ ---- -title: Deployment -icon: server -header_img: wizard.png ---- - -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/ - - -## Public facing wiki - -A simple way to run Wikked on a production server (_i.e._ a server accessible -from the internet) 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`. - - -## Advanced configurations - -### Background updates - -By default, when you edit a page, Wikked will invalidate any page with a query -in it. That page will be re-computed the next time you visit it. But this may -not work very well if you have a lot of queries. As an alternative, Wikked can -run background updates. - -First you enable background updates in the `get_wsgi_app` function from the previous -section. You just need to pass `async_update=True`. - -> If you want to use background updates locally, you can do `wk runserver -> --usetasks`. - -Now, you'll 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 - -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 771225b80f18 -r bba13de7a7d1 docs/templates/default.html --- a/docs/templates/default.html Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,56 +0,0 @@ -{% 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}}

-
- {% elif page.header_img %} -
-

{{ 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 771225b80f18 -r bba13de7a7d1 docs/templates/google.html --- a/docs/templates/google.html Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,33 +0,0 @@ -{% macro webfonts(fontnames) %} - -{% endmacro %} - -{% macro analytics(siteId) %} - -{% endmacro %} - -{% macro adsense(client, name, slot, width, height) %} - - -{% endmacro %} - diff -r 771225b80f18 -r bba13de7a7d1 docs/templates/inc/footer.html --- a/docs/templates/inc/footer.html Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6 +0,0 @@ - - diff -r 771225b80f18 -r bba13de7a7d1 docs/templates/inc/nav.html --- a/docs/templates/inc/nav.html Tue Oct 16 22:08:13 2018 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,17 +0,0 @@ - - -