]>
Commit | Line | Data |
---|---|---|
93f4ee45 | 1 | # web-7.0 [![Build Status](https://travis-ci.org/freenode/web-7.0.svg?branch=master)](https://travis-ci.org/freenode/web-7.0) |
22f798e7 | 2 | |
93f4ee45 | 3 | A shiny replacement for http://freenode.net. |
22f798e7 | 4 | |
22f798e7 | 5 | |
d0bfb193 EK |
6 | ## Building |
7 | ||
8 | You'll need our node.js dependencies: | |
9 | ||
10 | ```console | |
ba562ae6 | 11 | $ sudo npm install -g myth svgo |
d0bfb193 EK |
12 | ``` |
13 | ||
14 | Then, assuming a Python 3.4 (or later) installation: | |
15 | ||
16 | ```console | |
17 | $ python3 -m venv env | |
18 | $ . env/bin/activate | |
19 | $ pip install -r requirements.txt | |
20 | $ cms7 | |
21 | ``` | |
22 | ||
23 | If everything went well, you should see a lot of log output, and `out/` will | |
24 | have the website in it. | |
25 | ||
26 | Because we generate the site statically, you'll need to re-run `cms7` each | |
27 | time you change something. If your editor likes compile commands that can run | |
28 | from any directory, you can also use `cms7 -c /path/to/config.yml`. | |
29 | ||
30 | ||
31 | ## Contributing | |
32 | ||
33 | - Whenever possible, one commit per feature. | |
34 | - If feature/pull-request branches have only one developer, please regularly | |
35 | rebase them onto master until they are merged in. | |
36 | - Don't merge branches with meaningless commit messages; always squash them | |
37 | instead. | |
38 | - Wait for discussion of big changes. Your branches will still be here | |
39 | tomorrow. | |
40 | ||
5eeaa314 EK |
41 | Helpful tip for those merging PRs: you can browse the tree a merge would |
42 | result in by navigating to | |
43 | `https://github.com/freenode/web-7.0/tree/pull/XYZ/merge`, where `XYZ` is the | |
44 | pull request number. | |
45 | ||
7ec3c4aa | 46 | You can also go to `https://freenode.net/web-7.0/BRANCHNAME/` to see a |
5eeaa314 EK |
47 | build of any particular branch. This also works for *internal* pull requests |
48 | (they are named `pull-X`). | |
d0bfb193 | 49 | |
93f4ee45 | 50 | ## Architecture / Orientation |
f35be2c3 | 51 | |
d0bfb193 | 52 | The site is generated from |
93f4ee45 EK |
53 | [Markdown](https://daringfireball.net/projects/markdown/) sources and |
54 | [Jinja2](http://jinja.pocoo.org/) templates, found in `content/` and | |
55 | `templates/` respectively. The Travis build deploys to GitHub Pages | |
5eeaa314 | 56 | automatically on every push. |
f35be2c3 | 57 | |
93f4ee45 EK |
58 | Various modules convert the sources to a useful output structure. Eventually |
59 | cms7 will document this process, but for now: | |
f35be2c3 | 60 | |
93f4ee45 EK |
61 | - `content/pages/` contains plain pages which are rendered in `out/` using |
62 | `page.html`. | |
63 | - `content/news/` contains blog/news posts which are rendered in `out/news/` | |
64 | using `article.html`. | |
86588cc8 CD |
65 | - `content/kb/` contains KB categories: each directory `content/kb/X/` |
66 | has the entries for category `X`. These are rendered in `out/kb/answers/` | |
67 | with `kb.html`. | |
555f36d6 | 68 | |
86588cc8 CD |
69 | Indexes of these entries are rendered in `out/kb/` with `kb_index.html`, |
70 | according to a list in `config/kb.yml`. | |
f35be2c3 | 71 | |
f35be2c3 | 72 | |
93f4ee45 | 73 | ### Markdown metadata |
f35be2c3 | 74 | |
93f4ee45 EK |
75 | cms7 uses the markdown metadata extension, and recognises some special keys: |
76 | ||
77 | - `title` sets the page title | |
78 | - `slug` overrides the target URL: `pages/hello` with `slug: banana` would | |
79 | become `out/banana.html` | |
80 | - `template` overrides the template with which to render this Markdown file | |
81 | ||
82 | Blog-specific: | |
83 | ||
84 | - `author` | |
85 | - `date` | |
86 | ||
87 | ||
88 | ### Internal linking | |
89 | ||
90 | Everything that ends up in the final output has a name that identifies it to | |
91 | the rest of the website. If a file is derived directly from an input file, | |
92 | generally its name is derived from the name of the *input*. | |
f35be2c3 | 93 | |
93f4ee45 EK |
94 | - Markdown files like `content/pages/hello.md` are named their own name |
95 | relative to the content directory, minus their extension: `pages/hello`. | |
96 | - static resources like `static/img/cat.jpg` are named their own name | |
97 | relative to the repository root: `static/img/cat.jpg`. | |
98 | - Templates that are rendered from nothing (e.g. to make the index page) are | |
99 | named whatever the config file says to name them. | |
86588cc8 CD |
100 | - KB indexes are named `kb/index/X`, where X is the name of the index in |
101 | `config/kb.yml`. | |
93f4ee45 EK |
102 | |
103 | cms7 can generate a relative URL to anything with a name from any page. This | |
104 | should always be preferred over manually writing links. To generate a relative | |
1a4de58a | 105 | link from a Markdown document, just link to a name: |
93f4ee45 EK |
106 | |
107 | ```markdown | |
108 | [A page about frogs](pages/frog) | |
109 | ``` | |
110 | ||
111 | To do the same from a template, call `url_for`: | |
112 | ||
113 | ```html+jinja | |
114 | <a href="{{ url_for('pages/frog') }}">A page about frogs</a> | |
115 | ``` |