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