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 ## Architecture / Orientation
   7
   8 The site is statically generated from
   9 [Markdown](https://daringfireball.net/projects/markdown/) sources and
  10 [Jinja2](http://jinja.pocoo.org/) templates, found in `content/` and
  11 `templates/` respectively. The Travis build deploys to GitHub Pages
  12 automatically on every push to master.
  13
  14 Various modules convert the sources to a useful output structure. Eventually
  15 cms7 will document this process, but for now:
  16
  17 - `content/pages/` contains plain pages which are rendered in `out/` using
  18   `page.html`.
  19 - `content/news/` contains blog/news posts which are rendered in `out/news/`
  20   using `article.html`.
  21 - `content/faq/` contains FAQ categories: each directory `content/faq/X/`
  22   has the entries for category `X`. These are rendered in `out/faq/answers/`
  23   with `faq.html`.
  24
  25   Indexes of these entries are rendered in `out/faq/` with `faq_index.html`,
  26   according to a list in `config/faq.yml`.
  27
  28
  29 ### Markdown metadata
  30
  31 cms7 uses the markdown metadata extension, and recognises some special keys:
  32
  33 - `title` sets the page title
  34 - `slug` overrides the target URL: `pages/hello` with `slug: banana` would
  35   become `out/banana.html`
  36 - `template` overrides the template with which to render this Markdown file
  37
  38 Blog-specific:
  39
  40 - `author`
  41 - `date`
  42
  43
  44 ### Internal linking
  45
  46 Everything that ends up in the final output has a name that identifies it to
  47 the rest of the website. If a file is derived directly from an input file,
  48 generally its name is derived from the name of the *input*.
  49
  50 - Markdown files like `content/pages/hello.md` are named their own name
  51   relative to the content directory, minus their extension: `pages/hello`.
  52 - static resources like `static/img/cat.jpg` are named their own name
  53   relative to the repository root: `static/img/cat.jpg`.
  54 - Templates that are rendered from nothing (e.g. to make the index page) are
  55   named whatever the config file says to name them.
  56 - FAQ indexes are named `faq/index/X`, where X is the name of the index in
  57   `config/faq.yml`.
  58
  59 cms7 can generate a relative URL to anything with a name from any page. This
  60 should always be preferred over manually writing links. To generate a relative
  61 link from a Markdown template, just link to a name:
  62
  63 ```markdown
  64 [A page about frogs](pages/frog)
  65 ```
  66
  67 To do the same from a template, call `url_for`:
  68
  69 ```html+jinja
  70 <a href="{{ url_for('pages/frog') }}">A page about frogs</a>
  71 ```
  72
  73
  74 ## TODO
  75 - [ ] Get the basic static page up, and how to connect (latest two news about
  76   the reformation + about page, kinda) scheduled release: 2016-02-29
  77   - [x]  Design ready enough
  78   - [x] Preprocessor ready
  79   - [x] Templates ready enough
  80   - [ ] Content ready
  81 - [ ] FAQ pages structure, start adding FAQ's (note: tagging could be a good thing for searching and finding)
  82 - [ ] Add possibility to edit on-site integrated with services (log in with your nickserv acc)
  83 - [ ] Gms integration
  84 - [ ] Further development TODO: TODO