git.haldean.org docstore / 6aeb8d8
Remove dead articles Will Brown 9 years ago
3 changed file(s) with 0 addition(s) and 112 deletion(s). Raw diff Collapse all Expand all
+0
-7
text/article.md less more
0 this is an article
1 ===
2
3 in summary:
4
5 * this is a thing
6 * this is another
+0
-101
text/docstore.md less more
0 docstore: Easy Public Document Storage
1 ====
2
3 toc-here
4
5 What is docstore?
6 ---
7 docstore is an incredibly simple collection of scripts that allow you to very
8 simply host a number of static Markdown documents. I designed it with the
9 intention of making it very easy to add and update documents while keeping the
10 system itself as simple as possible.
11
12 Installing docstore
13 ---
14 docstore itself is just a few scripts which can be [downloaded as a ZIP
15 file][zipfile] or [cloned on Github][github] (pull requests welcome!). It
16 requires a Redis server running on the default port on the same machine that
17 serves the documents. It also requires the `BeautifulSoup`, `jinja2` and `redis`
18 python modules, both of which are available using `pip` or `easy_install`. The
19 `redis` module is not yet Python 3 compatible -- docstore will be Python 3
20 compatible as soon as the `redis` module is. Until then, it works on Python 2.5
21 through 2.7.
22
23 Note that `BeautifulSoup` is not required if you choose to not use the table of
24 contents feature.
25
26 [zipfile]: https://github.com/haldean/docstore/zipball/master
27 [github]: https://github.com/haldean/docstore/
28
29 Using docstore
30 ---
31 Each page in docstore has a name and content (and that's it). The name must be a
32 string of alphanumeric characters, and may not contain spaces. The content can
33 be whatever you want. Documents can be accessed at `mydomain.com/title`, where
34 `title` is the title of the document.
35
36 docstore assumes that it is running on a different machine than the one you are
37 updating it from. As such, there are a number of scripts in the `scripts/`
38 directory which make it easy to remotely update the documents on your store.
39 Before they can be run, though, your server must be configured.
40
41 ### Configuring the server
42 `docstore.py` is the meat of docstore -- it serves the pages from redis on port
43 8000. The port can be changed by changing the `port = 8000` line at the top of
44 `docstore.py`. I recommend running `docstore.py` as an unprivileged user on a
45 higher port, and use a webserver to proxy to that port, for both security
46 reasons and because docstore can't serve static files. To run
47 [docstore.haldean.org][ds], I run mongrel2 which proxies to
48 [haldean.org:8000][dsp] for any URL that doesn't match "`static/`". Requests for
49 static content like stylesheets and images then can be served from the
50 filesystem.
51
52 [ds]: http://docstore.haldean.org
53 [dsp]: http://haldean.org:8000
54
55 ### Configuring output
56 docstore uses the two Jinja2 templates stored in the `templates/` directory to
57 style the output. `content.html` is the template used for the documents, and
58 `index.html` is used for the listing of all of the documents. If you want to
59 design your own content template, the template variable `content` contains the
60 document, and `title` contains the title of the page. The index template takes
61 only one parameter, `slugs`, which is a list of page titles. Note that there's
62 no requirement that you have a listing of documents on the homepage -- you can
63 safely remove the `slugs` variable from your template and have a static
64 homepage.
65
66 ### Remotely updating documents
67 docstore comes with two convenience scripts: `mkpage.sh` and `rmpage.sh`.
68 mkpage takes one or two arguments. The first argument is the page title. If the
69 second argument is provided, it is the Markdown file to be uploaded as the new
70 page. If I wanted to upload the file `docstore.md` as `docstore`, I would run:
71
72 scripts/mkpage.sh docstore docstore.md
73
74 If the second argument is omitted, it will fire up your editor (defined in the
75 `EDITOR` shell variable). When you are finished writing your article, just save
76 and quit your editor. It will confirm that you want to upload what you just
77 wrote before committing the change. If you provide the name of an
78 already-existing document, it will insert the page into your editor so you can
79 edit it inline -- for example, if I wanted to edit the document I uploaded in
80 the last example, I could run:
81
82 EDITOR=gvim scripts/mkpage.sh docstore
83
84 And gvim would open with the contents of docstore already in the editor. If I
85 make any changes, I can save and quit and it will upload my changes.
86
87 Note that these scripts require you to use SSH keys to connect to your server --
88 simple passphrase authentication will not work, as it is designed to work
89 without user interaction. If your keys have a passphrase, you can use `ssh-add`
90 to unlock your key in `ssh-agent`, which will then allow mkpage and rmpage to
91 upload without user interaction.
92
93
94
95
96
97
98
99
100
+0
-4
text/test.md less more
0 THIS IS JUST A TEST
1 ===
2
3 Herp derp. More and more tests.