jfr.im git - irc/freenode/web-7.0.git/blame_incremental

... / ...

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) [![irc: #freenode-website](https://img.shields.io/badge/irc-%23freenode--website-brightgreen.svg)](https://webchat.freenode.net/?channels=freenode-website)
	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	$ sudo npm install -g postcss-cli svgo
	12	$ npm install
	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
	42	Please comply with the [contribution guidelines](CONTRIBUTING.md)
	43
	44	Helpful tip for those merging PRs: you can browse the tree a merge would
	45	result in by navigating to
	46	`https://github.com/freenode/web-7.0/tree/pull/XYZ/merge`, where `XYZ` is the
	47	pull request number.
	48
	49	You can also go to `https://freenode.net/web-7.0/BRANCHNAME/` to see a
	50	build of any particular branch. This also works for internal pull requests
	51	(they are named `pull-X`).
	52
	53	## Architecture / Orientation
	54
	55	The site is generated from
	56	[Markdown](https://daringfireball.net/projects/markdown/) sources and
	57	[Jinja2](http://jinja.pocoo.org/) templates, found in `content/` and
	58	`templates/` respectively. The Travis build deploys to GitHub Pages
	59	automatically on every push.
	60
	61	Various modules convert the sources to a useful output structure. Eventually
	62	cms7 will document this process, but for now:
	63
	64	- `content/pages/` contains plain pages which are rendered in `out/` using
	65	`page.html`.
	66	- `content/news/` contains blog/news posts which are rendered in `out/news/`
	67	using `article.html`.
	68	- `content/kb/` contains KB categories: each directory `content/kb/X/`
	69	has the entries for category `X`. These are rendered in `out/kb/answers/`
	70	with `kb.html`.
	71
	72	Indexes of these entries are rendered in `out/kb/` with `kb_index.html`,
	73	according to a list in `config/kb.yml`.
	74
	75
	76	### Markdown metadata
	77
	78	cms7 uses the markdown metadata extension, and recognises some special keys:
	79
	80	- `title` sets the page title
	81	- `slug` overrides the target URL: `pages/hello` with `slug: banana` would
	82	become `out/banana.html`
	83	- `template` overrides the template with which to render this Markdown file
	84
	85	Blog-specific:
	86
	87	- `author`
	88	- `date`
	89	- `enclosure` sets the podcast URL of an article
	90
	91
	92	### Internal linking
	93
	94	Everything that ends up in the final output has a name that identifies it to
	95	the rest of the website. If a file is derived directly from an input file,
	96	generally its name is derived from the name of the input.
	97
	98	- Markdown files like `content/pages/hello.md` are named their own name
	99	relative to the content directory, minus their extension: `pages/hello`.
	100	- static resources like `static/img/cat.jpg` are named their own name
	101	relative to the repository root: `static/img/cat.jpg`.
	102	- Templates that are rendered from nothing (e.g. to make the index page) are
	103	named whatever the config file says to name them.
	104	- KB indexes are named `kb/index/X`, where X is the name of the index in
	105	`config/kb.yml`.
	106
	107	cms7 can generate a relative URL to anything with a name from any page. This
	108	should always be preferred over manually writing links. To generate a relative
	109	link from a Markdown document, just link to a name:
	110
	111	```markdown
	112	[A page about frogs](pages/frog)
	113	```
	114
	115	To do the same from a template, call `url_for`:
	116
	117	```html+jinja
	118	<a href="{{ url_for('pages/frog') }}">A page about frogs</a>
	119	```