Deprecate this repo for leap_se.
[leap_doc.git] / README.md
1 **DO NOT USE THIS REPO**
2
3 This repo is no longer in use, please use the `leap_se` repo instead.
4
5 * https://leap.se/git/leap_se.git
6 * https://github.com/leapcode/leap_se
7
8
9 LEAP DOCUMENTATION
10 =================================
11
12 Files in the directory "docs" show up automatically at https://leap.se/docs when this repository is pushed.
13
14
15 Directory structure
16 ---------------------------------
17
18 Every directory corresponds to a single web page. Within each directory, there are source files for different languages.
19
20 For example:
21
22     docs/
23       client/
24         en.haml    -- used for https://leap.se/en/docs/client
25         es.haml    -- used for https://leap.se/es/docs/client
26
27 If you don't care about translating a page, and it has no children, you can omit the directory:
28
29     docs/
30       client.haml  -- user for https://leap.se/*/docs/client
31
32 Menu
33 ---------------------------------
34
35 A page does not show up in the navigation unless it appears in menu.txt.
36
37 The order in menu.txt determines the order in the navigation.
38
39 Supported syntaxes
40 ---------------------------------
41
42 Depending the the file extension, the file with be parsed like so:
43
44     .haml       -- HAML
45     .md         -- Markdown
46     .markdown   -- Markdown
47     .txt        -- Textile
48     .textile    -- Textile
49     .rst        -- ReStructuredText
50
51 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.
52
53 There are a couple options to preview your source files without needing to run the web server:
54
55 * Markdown preview for Chrome: https://chrome.google.com/webstore/detail/markdown-preview/jmchmkecamhbiokiopfpnfgbidieafmd
56 * Markdown preview for Sublime: https://github.com/revolunet/sublimetext-markdown-preview
57 * 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)
58
59 Setting page properties
60 ---------------------------------
61
62 HAML files are rendered as templates, but the other lightweight markup files are treated as static files.
63
64 The one exception is that every file can have a "properties header". It looks like this:
65
66     @title = "A fine page"
67     @toc = false
68
69     continue on here with body text.
70
71 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`.
72
73 Available properties:
74
75 * `@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).
76 * `@nav_title` -- The title for the navigation to this page, as well as the HTML title if @title is not set.
77 * `@toc` -- If set to `false`, don't include a table of contents when rendering the file. This only applies to .rst and .md files.
78 * `@layout` -- Manually set the layout template to use for rendering this page.
79 * `@author` -- The author credit for the page.