Mercurial > wikked

annotate docs/pages/02_overview.md @ 444:2f68a463cb06

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cm: Replace Grunt/RequireJS with Gulp/Browserify. Yes, I know, this sounds like it's 2014 or something, and cool kids are now actually on webpack or whatever. Anyway, besides the change to a `gulpfile`, it also moves all dependencies over to `npm` (via the `package.json` file), which cleans up the repository nicely, and replaces awkward JS imports with simpler `require` statements.
author Ludovic Chabant <ludovic@chabant.com>
date Wed, 03 Jan 2018 00:51:59 -0800
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: Overview
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 icon: book
398
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
4 header_img: melting.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's data is entirely stored in text files on disk. All you ever need, or
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
8 should really care about, are those text files, and the source control
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
9 repository which contains their history. Wikked may create some other files --
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
10 cache files, indices, etc. -- but they can always be safely deleted and
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
11 re-created.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
12
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
13
398
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
14 ## General features
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
15
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
16 Wikked implements the usual [wiki][] concepts of being able to edit pages, look
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
17 at their history, revert to previous revisions, or easily link to other pages.
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
18
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
19 Wikked also supports the ability to include a page into another page, to assign
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
20 metadata (like categories) to pages, and to query pages based on that metadata.
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
21 So for example you can display a list of all pages under the category "_Witches
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
22 of Oz_".
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
23
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
24 Finally, because the wiki sits on top of a standard source controlled
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
25 repository with text files in it, you can edit, pull, push, merge, rebase, and
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
26 more. This may not be shown correctly on the web history page, but you can still
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
27 do that.
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
28
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
29 [wiki]: https://en.wikipedia.org/wiki/Wiki
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
30
0f4032dafc1f docs: Adjustments to documentation.
Ludovic Chabant <ludovic@chabant.com>
parents: 397
diff changeset
31
382
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
32 ## The wiki folder
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
33
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
34 If you look at your new wiki, you should see a file called `Main page.md`, along
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
35 with a few hidden files and directories.
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 * Each page's text is stored in a file whose name is the name of the page --
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
38 like that `Main page.md`. That name is important, since that's what you'll use
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
39 for linking to it, and what will show up in that page's URL. A page named
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
40 `Toto.md` would be available at the URL `/read/Toto`.
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 * Sub-directories also map to sub-folders in page names and URLs, so a file
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
43 located at `Villains/Flying monkeys.md` would be available at
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
44 `/read/Villains/Flying monkeys.md`.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
45
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
46 * There's a `.wiki` folder that was created in the wiki root. This folder is
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
47 a cache, and can generally be safely deleted and re-created with the `wk
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
48 reset` command. You may however have some [local configuration
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
49 file(s)][config] in there, which we'll talk about later, so watch out before
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
50 deleting that folder.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
51
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
52 * There's also some source control related files in there, like a `.hg` folder
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
53 and `.hgignore` file in the case of Mercurial. Don't touch those, they're
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
54 important (they store your pages' history). You can learn about them using the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
55 wonders of the internet.
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 > There's nothing preventing you from using accented or non-latin characters for
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
58 > a new page name, except for characters that would be invalid for a file name.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
59 > However, please note that most revision control systems are going to behave
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
60 > badly if you'll be working with your repository on mixed systems (_i.e._
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
61 > Windows, Mac, Linux).
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
62
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
63
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
64 ## Limitations
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
65
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
66 Wikked was written mainly for a small group of editors in mind. It's especially
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
67 well suited for a personal digital notebook, a private family documents
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
68 repository, or a wiki for a small team of people.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
69
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
70 The main limitation of Wikked comes into play when you increase the number of
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
71 contributors -- *not* when you increase the number of visitors. Once the website
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
72 is cached, all requests are done against the SQL database, and search is done
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
73 through the indexer. This means you can scale quite well as long as you have the
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
74 appropriate backend (and as long as I don't write anything stupid in the code).
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 However, user accounts are stored in a text file, and must be added by hand by
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
77 an administrator, so it's impossible to scale this up to hundreds or thousands
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
78 of users. You could probably improve this by adding a different user account
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
79 backend, but when those users start editing pages, each edit must write to a
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
80 separate file on disk, and be committed to a source control repository, and this
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
81 will probably prove to be a bottleneck anyway at some point.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
82
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
83 In summary: Wikked should be able to handle lots of visitors, but not too
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
84 many contributors.
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
85
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
86 ## Support
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 If you need assistance with Wikked, [contact me directly][me] or report an issue
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
89 on the [GitHub bug tracker][bugs].
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 [me]: http://ludovic.chabant.com
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
92 [bugs]: https://github.com/ludovicchabant/Wikked/issues
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
93 [config]: {{pcurl('configuration')}}
3a61f45702cb docs: Add documentation site.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
94