Skip to content

Commit c503c31

Browse files
lovelydinosaurlovelydinosaur
authored
Merge pull request #4 from encode/docs
Documentation.
2 parents 06fa5fd + 75565a2 commit c503c31

5 files changed

Lines changed: 240 additions & 86 deletions

File tree

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# MkDocs
22

3-
MkDocs is a smart, simple website design tool using Markdown, templated HTML, and CSS.
3+
MkDocs is a smart, simple website design tool using [Markdown](writing.md), [templated HTML](styling.md#templates), and static [media files](styling.md#media).
44

55
## Installation
66

‎docs/navigation.md‎

Lines changed: 48 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,55 @@
11
# Site Navigation
22

3-
Wang a load of different markdown files up there.
3+
When building sites with multiple pages, use `index.md` or `README.md` for root URLs.
4+
5+
| **File** | **URL** |
6+
|-----------------|-----|
7+
| `index.md` | `/`
8+
| `markdown.md` | `/markdown/`
9+
| `navigation.md` | `/navigation/`
10+
| `styling.md` | `/styling/`
11+
12+
Pages should use the `.md` file extension in order to be rendered as markdown. Other documents are served unmodified as [media files](styling.md#media).
413

514
## Interlinking
615

7-
Look just use relative file interlinking `[about](about.md)`.
16+
Use relative interlinking to help users navigate between documents.
17+
18+
Link to another markdown file in the same directory…
19+
20+
```markdown
21+
See our [contribution documentation](CONTRIBUTING.md) for more details on getting involved.
22+
```
23+
24+
Link to a document in a subdirectory…
25+
26+
```markdown
27+
The [tutorial](tutorial/getting-started.md) will help get you started.
28+
```
29+
30+
Link to a document in a parent directory…
31+
32+
```markdown
33+
Back to the [homepage](../index.md).
34+
```
35+
36+
## Configuration
37+
38+
You can include site-wide navigation by using the `mkdocs.toml` configuration.
39+
40+
```
41+
[mkdocs]
42+
version = 2
843
9-
## Navigation menu
44+
[site]
45+
title = "MkDocs"
46+
favicon = "📘"
47+
nav = [
48+
{title="Introduction", path="index.md"},
49+
{title="Writing Markdown", path="markdown.md"},
50+
{title="Site Navigation", path="navigation.md"},
51+
{title="HTML Styling", path="styling.md"}
52+
]
53+
```
1054

11-
Mush yourself up a navigation menu in the config.
55+
This allows the theme to display navigation controls, as well as including `← previous` and `next →` links.

‎docs/styling.md‎

Lines changed: 18 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
1-
# Styling
1+
# HTML Styling
22

33
Styling is handled with HTML templating and regular web design.
44

55
## Templates
66

7-
Markdown documents are rendered using Jinja templating.
7+
Anything in the `/templates/` directory is treated as a [Jinja template](https://jinja.palletsprojects.com/en/stable/templates/), and is used to render pages, rather than being served directly. You can override templates locally and adapt them to make layout changes.
88

9-
The following templates are included in the default theme...
10-
11-
* `templates/base.html`
9+
The base template for rendering markdown pages is **`templates/base.html`**.
1210

1311
```html
1412
<html>
@@ -39,42 +37,25 @@ The following templates are included in the default theme...
3937
</html>
4038
```
4139

42-
The base template used for rendering markdown pages. You can override this template locally and adapt it to make layout changes.
43-
44-
* `templates/favicon.svg`
45-
46-
```html
47-
{% set escaped %}<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="90">{{ config['site']['favicon'] }}</text></svg>{% endset %}{{ escaped | e }}
48-
```
49-
50-
Included by the base template. This is an SVG used for the favicon, that is included as an inline `data:` URL.
40+
The following templates are included in [the default theme](https://github.com/encode/mkdocs/blob/main/src/mkdocs/theme/)...
5141

52-
Enables the `config['site']['favicon']` field to config a unicode emoji to use as the site favicon.
42+
* `templates/base.html`- The base template used for rendering markdown pages.
43+
* `templates/favicon.svg` - an SVG used for the favicon, that displays the `config['site']['favicon']` emoji.
44+
* `templates/pagination.html` - Included by the base template. Renders next and previous page controls.
5345

54-
* `templates/pagination.html`
55-
56-
```html
57-
{% if page.previous or page.next %}
58-
<div class="pagination">
59-
{% if page.previous %}
60-
<a class="previous" href="{{ page.previous['url']}}">← {{ page.previous['title']}}</a>
61-
{% endif %}
62-
{% if page.next %}
63-
<a class="next" href="{{ page.next['url']}}">{{ page.next['title']}} →</a>
64-
{% endif %}
65-
</div>
66-
{% endif %}
67-
```
46+
## Media
6847

69-
Included by the base template. Renders next and previous page controls.
48+
Any files that are not Markdown pages `*.md`, or templates `/templates/*`, are treated as media documents and are included in the website without modification.
7049

71-
## Media
50+
This can include images, stylesheets, javascript, fonts, video and audio.
7251

73-
The default theme includes the following assets:
52+
The default theme includes the following media documents...
7453

75-
* [`css/theme.css`](css/theme.css) &mdash; Copy and overide this file in order to change the color palette, the typography, or to other style changes.
76-
* [`css/highlightjs.min.css`](css/highlightjs.min.css) &mdash; The default theme uses the `github-dark` code highlighting style. Override this file to use a different `highlight.js` code highlighting style.
77-
* [`css/highlightjs-copy.min.css`](css/highlightjs.min.css) &mdash; *...*
78-
* [`js/theme.js`](js/theme.js) &mdash; Copy and override this file in order to add custom scripting.
79-
* [`js/highlightjs.min.js`](js/highlightjs.min.js) &mdash; The default theme uses the default supported languages with `highlight.js`. Override this file to support a different set of programming languages.
54+
* [`css/theme.css`](css/theme.css)
55+
* [`css/highlightjs.min.css`](css/highlightjs.min.css)
56+
* [`css/highlightjs-copy.min.css`](css/highlightjs-copy.min.css)
57+
* [`js/theme.js`](js/theme.js)
58+
* [`js/highlightjs.min.js`](js/highlightjs.min.js)
8059
* [`js/highlightjs-copy.min.js`](js/highlightjs-copy.min.js)
60+
61+
You can override these locally to style the color scheme, the typography & layout, or to adapt the `highlight.js` code highlighting.

0 commit comments

Comments
 (0)