]>
Commit | Line | Data |
---|---|---|
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) | |
2 | ||
3 | A shiny replacement for http://freenode.net. | |
4 | ||
5 | ||
6 | ## Building | |
7 | ||
8 | You'll need our node.js dependencies: | |
9 | ||
10 | ```console | |
11 | $ npm install -g myth svgo | |
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 | ||
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 | ||
46 | You can also go to `https://freenode.github.io/web-7.0/BRANCHNAME/` to see a | |
47 | build of any particular branch. This also works for *internal* pull requests | |
48 | (they are named `pull-X`). | |
49 | ||
50 | ## Architecture / Orientation | |
51 | ||
52 | The site is generated from | |
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 | |
56 | automatically on every push. | |
57 | ||
58 | Various modules convert the sources to a useful output structure. Eventually | |
59 | cms7 will document this process, but for now: | |
60 | ||
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`. | |
65 | - `content/faq/` contains FAQ categories: each directory `content/faq/X/` | |
66 | has the entries for category `X`. These are rendered in `out/faq/answers/` | |
67 | with `faq.html`. | |
68 | ||
69 | Indexes of these entries are rendered in `out/faq/` with `faq_index.html`, | |
70 | according to a list in `config/faq.yml`. | |
71 | ||
72 | ||
73 | ### Markdown metadata | |
74 | ||
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*. | |
93 | ||
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. | |
100 | - FAQ indexes are named `faq/index/X`, where X is the name of the index in | |
101 | `config/faq.yml`. | |
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 | |
105 | link from a Markdown template, just link to a name: | |
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 | ``` | |
116 | ||
117 | ||
118 | ## TODO | |
119 | - [ ] Get the basic static page up, and how to connect (latest two news about | |
120 | the reformation + about page, kinda) scheduled release: 2016-02-29 | |
121 | - [x] Design ready enough | |
122 | - [x] Preprocessor ready | |
123 | - [x] Templates ready enough | |
124 | - [ ] Content ready | |
125 | - [ ] FAQ pages structure, start adding FAQ's (note: tagging could be a good thing for searching and finding) | |
126 | - [ ] Add possibility to edit on-site integrated with services (log in with your nickserv acc) | |
127 | - [ ] Gms integration | |
128 | - [ ] Further development TODO: TODO |