UNPKG

apos-docs

Version:

Documentation static site generator built with Eleventy.

github.com/Apostolique/apos-docs

Apostolique/apos-docs

49 lines (34 loc) • 2.55 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
# Design choices High level overview for the apos-docs design decisions. ## Markdown * The markdown should be readable by itself from GitHub. This means that links must work in the context of the repository and be rewritten for the static site. * Avoid custom markdown syntax unless absolutely necessary. * The page's first h1 tag will be used as the page title. The site name will be appended to it. * The page's first p tag will be used as the page description. * Pages that have multiple headings will have a table of content generated. * Each page in the generated site will include an edit link that points to the same page in the GitHub repository. ## Images * Support jpg, png, gif * Links to images must work in the context of the repository and be rewritten for the static site. * Two or more images on the same line are laid out as a row instead of stacking. ## Links You write links the way that makes sense when reading the markdown on GitHub, and they get rewritten to match the generated site: * A link to another page drops the `.md` and gains a trailing slash, so `./button.md` becomes `/button/`. `README.md` resolves to the directory itself. * Relative links resolve against the page they're written on. Absolute links starting with your docs directory work too, so `/docs/button.md` and `./button.md` reach the same page. * A link pointing outside the docs directory can't exist on the site, so it's rewritten to the file on GitHub. `../src/styles/` becomes a link into the repository. Images work the same way, except they point at raw.githubusercontent.com so they still render. * Anchors and `mailto:` links are left alone. * The base url is added to internal links, so the site works from a subdirectory. Links to other sites get `target="_blank"` and `rel="noopener noreferrer"`. Links to your own site are excluded from that, which is what the url option is for. Links rewritten to GitHub count as leaving the site and open in a new tab too. ## Routing * `README.md` files become `index.html`. * Other pages such as `page.md` become `page/index.html`. * Pages that end in `.draft.md` are excluded from the site. * A `CHANGELOG.md` in the repository root becomes `changelog/index.html`. Its table of content only lists the top level headings. * A 404 page is generated for you. ## Navigation Stored in `docs/_data/nav.yml` and contains: * Nested list of links to navigate through the docs' pages. A link can hold its own `links` list to group pages under it, as deep as needed. * List of social media links.