added text explaining use of rev in doc _mac
[leap_doc.git] / README.md
1 LEAP DOCUMENTATION
2 =================================
3
4 Files in the directory "docs" show up automatically at https://leap.se/docs when this repository is pushed.
5
6
7 Directory structure
8 ---------------------------------
9
10 Every directory corresponds to a single web page. Within each directory, there are source files for different languages.
11
12 For example:
13
14     docs/
15       client/
16         en.haml    -- used for https://leap.se/en/docs/client
17         es.haml    -- used for https://leap.se/es/docs/client
18
19 If you don't care about translating a page, and it has no children, you can omit the directory:
20
21     docs/
22       client.haml  -- user for https://leap.se/*/docs/client
23
24 Menu
25 ---------------------------------
26
27 A page does not show up in the navigation unless it appears in menu.txt.
28
29 The order in menu.txt determines the order in the navigation.
30
31 Supported syntaxes
32 ---------------------------------
33
34 Depending the the file extension, the file with be parsed like so:
35
36     .haml       -- HAML
37     .md         -- Markdown
38     .markdown   -- Markdown
39     .txt        -- Textile
40     .textile    -- Textile
41     .rst        -- ReStructuredText
42
43 Markdown is rendered using RDiscount, Textile is rendered using RedCloth, and RST is rendered using docutils. Markdown is recommended, because it supports table of contents, although the markup is limited.
44
45 There are a couple options to preview your source files without needing to run the web server:
46
47 * Markdown preview for Chrome: https://chrome.google.com/webstore/detail/markdown-preview/jmchmkecamhbiokiopfpnfgbidieafmd
48 * Markdown preview for Sublime: https://github.com/revolunet/sublimetext-markdown-preview
49 * Markdown preview for Firefox: https://addons.mozilla.org/de/firefox/addon/markdown-viewer/  (see https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer/reviews/423328/ for rendering .md file extensions)
50
51 Setting page properties
52 ---------------------------------
53
54 HAML files are rendered as templates, but the other lightweight markup files are treated as static files.
55
56 The one exception is that every file can have a "properties header". It looks like this:
57
58     @title = "A fine page"
59     @toc = false
60
61     continue on here with body text.
62
63 The properties start with '@' and are stripped out of the source file before it is rendered. Property header lines are evaluated as ruby. All properties are optional and they are inherited, including `@title`.
64
65 Available properties:
66
67 * `@title` -- The title for the page, appearing as in an H1 on the top of the page and as the HTML title. Also used for navigation title if `@nav_title` is not set. The inline H1 title does not appear unless `@title` is explicitly set for this page (i.e. the inherited value of `@title` does not trigger the automatic H1).
68 * `@nav_title` -- The title for the navigation to this page, as well as the HTML title if @title is not set.
69 * `@toc` -- If set to `false`, don't include a table of contents when rendering the file. This only applies to .rst and .md files.
70 * `@layout` -- Manually set the layout template to use for rendering this page.
71 * `@author` -- The author credit for the page.