README.md

   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 $ sudo 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/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`.
  68
  69   Indexes of these entries are rendered in `out/kb/` with `kb_index.html`,
  70   according to a list in `config/kb.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 - KB indexes are named `kb/index/X`, where X is the name of the index in
 101   `config/kb.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 document, 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   - [x] Content ready
 125 - [x] KB pages structure, start adding KB'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