Skip to content

Commit 1788e60

Browse files
lovelydinosaurlovelydinosaur
committed
Update documentation
1 parent cd40054 commit 1788e60

5 files changed

Lines changed: 153 additions & 64 deletions

File tree

‎configuration/index.html‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
55
<title>MkDocs</title>
6-
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&#34;http://www.w3.org/2000/svg&#34; viewBox=&#34;0 0 100 100&#34;&gt;&lt;text y=&#34;.9em&#34; font-size=&#34;90&#34;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
6+
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 100 100&quot;&gt;&lt;text y=&quot;.9em&quot; font-size=&quot;90&quot;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
77
<link rel="stylesheet" href="../css/highlightjs.min.css">
88
<link rel="stylesheet" href="../css/highlightjs-copy.min.css">
99
<link rel="stylesheet" href="../css/theme.css">
@@ -101,13 +101,13 @@ <h3 id="loaders"><a class="toclink" href="#loaders">Loaders</a></h3>
101101
* `mkdocs build`
102102
-->
103103

104-
<div class="pagination">
105-
106-
107-
<a class="next" href="../">Introduction →</a>
108-
109-
</div>
110-
104+
<div class="pagination">
105+
106+
107+
<a class="next" href="../">Introduction →</a>
108+
109+
</div>
110+
111111
</main>
112112
</body>
113113
</html>

‎index.html‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
55
<title>MkDocs</title>
6-
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&#34;http://www.w3.org/2000/svg&#34; viewBox=&#34;0 0 100 100&#34;&gt;&lt;text y=&#34;.9em&#34; font-size=&#34;90&#34;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
6+
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 100 100&quot;&gt;&lt;text y=&quot;.9em&quot; font-size=&quot;90&quot;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
77
<link rel="stylesheet" href="css/highlightjs.min.css">
88
<link rel="stylesheet" href="css/highlightjs-copy.min.css">
99
<link rel="stylesheet" href="css/theme.css">
@@ -62,13 +62,13 @@ <h2 id="custom-styling"><a class="toclink" href="#custom-styling">Custom styling
6262
</ol>
6363
<p>Simple <a href="styling/">styling adaptations</a> include customising the colour scheme, the typography, or choosing the code highlighting style.</p>
6464

65-
<div class="pagination">
66-
67-
68-
<a class="next" href="writing/">Writing Markdown →</a>
69-
70-
</div>
71-
65+
<div class="pagination">
66+
67+
68+
<a class="next" href="writing/">Writing Markdown →</a>
69+
70+
</div>
71+
7272
</main>
7373
</body>
7474
</html>

‎navigation/index.html‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
55
<title>MkDocs</title>
6-
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&#34;http://www.w3.org/2000/svg&#34; viewBox=&#34;0 0 100 100&#34;&gt;&lt;text y=&#34;.9em&#34; font-size=&#34;90&#34;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
6+
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 100 100&quot;&gt;&lt;text y=&quot;.9em&quot; font-size=&quot;90&quot;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
77
<link rel="stylesheet" href="../css/highlightjs.min.css">
88
<link rel="stylesheet" href="../css/highlightjs-copy.min.css">
99
<link rel="stylesheet" href="../css/theme.css">
@@ -111,15 +111,15 @@ <h2 id="configuration"><a class="toclink" href="#configuration">Configuration</a
111111
]
112112
</code></pre>
113113

114-
<div class="pagination">
115-
116-
<a class="previous" href="../writing/">← Writing Markdown</a>
117-
118-
119-
<a class="next" href="../styling/">HTML Styling →</a>
120-
121-
</div>
122-
114+
<div class="pagination">
115+
116+
<a class="previous" href="../writing/">← Writing Markdown</a>
117+
118+
119+
<a class="next" href="../styling/">HTML Styling →</a>
120+
121+
</div>
122+
123123
</main>
124124
</body>
125125
</html>

‎styling/index.html‎

Lines changed: 117 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
55
<title>MkDocs</title>
6-
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&#34;http://www.w3.org/2000/svg&#34; viewBox=&#34;0 0 100 100&#34;&gt;&lt;text y=&#34;.9em&#34; font-size=&#34;90&#34;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
6+
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 100 100&quot;&gt;&lt;text y=&quot;.9em&quot; font-size=&quot;90&quot;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
77
<link rel="stylesheet" href="../css/highlightjs.min.css">
88
<link rel="stylesheet" href="../css/highlightjs-copy.min.css">
99
<link rel="stylesheet" href="../css/theme.css">
@@ -25,7 +25,8 @@
2525
<ul>
2626
<li><a href="#html-styling">HTML Styling</a><ul>
2727
<li><a href="#templates">Templates</a></li>
28-
<li><a href="#media">Media</a></li>
28+
<li><a href="#pages">Pages</a></li>
29+
<li><a href="#statics">Statics</a></li>
2930
</ul>
3031
</li>
3132
</ul>
@@ -42,39 +43,128 @@ <h2 id="templates"><a class="toclink" href="#templates">Templates</a></h2>
4243
&lt;head&gt;
4344
&lt;meta charset=&quot;utf-8&quot;&gt;
4445
&lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1.0&quot;&gt;
45-
&lt;title&gt;{{ config['site']['title'] }}&lt;/title&gt;
46-
&lt;link rel=&quot;icon&quot; href=&quot;data:image/svg+xml,{% include 'favicon.svg' %}&quot;&gt;
47-
&lt;link rel=&quot;stylesheet&quot; href=&quot;/css/highlightjs.min.css&quot;&gt;
48-
&lt;link rel=&quot;stylesheet&quot; href=&quot;/css/highlightjs-copy.min.css&quot;&gt;
49-
&lt;link rel=&quot;stylesheet&quot; href=&quot;/css/theme.css&quot;&gt;
50-
&lt;script src=&quot;/js/highlightjs.min.js&quot;&gt;&lt;/script&gt;
51-
&lt;script src=&quot;/js/highlightjs-copy.min.js&quot;&gt;&lt;/script&gt;
52-
&lt;script src=&quot;/js/theme.js&quot;&gt;&lt;/script&gt;
46+
&lt;title&gt;{{ config.site.title }}&lt;/title&gt;
47+
&lt;link rel=&quot;icon&quot; href=&quot;data:image/svg+xml,&amp;lt;svg xmlns=&amp;quot;http://www.w3.org/2000/svg&amp;quot; viewBox=&amp;quot;0 0 100 100&amp;quot;&amp;gt;&amp;lt;text y=&amp;quot;.9em&amp;quot; font-size=&amp;quot;90&amp;quot;&amp;gt;{{ config['site']['favicon'] }}&amp;lt;/text&amp;gt;&amp;lt;/svg&amp;gt;&quot;&gt;
48+
&lt;link rel=&quot;stylesheet&quot; href=&quot;{{ '/css/highlightjs.min.css' | url }}&quot;&gt;
49+
&lt;link rel=&quot;stylesheet&quot; href=&quot;{{ '/css/highlightjs-copy.min.css' | url }}&quot;&gt;
50+
&lt;link rel=&quot;stylesheet&quot; href=&quot;{{ '/css/theme.css' | url }}&quot;&gt;
51+
&lt;script src=&quot;{{ '/js/highlightjs.min.js' | url }}&quot;&gt;&lt;/script&gt;
52+
&lt;script src=&quot;{{ '/js/highlightjs-copy.min.js' | url }}&quot;&gt;&lt;/script&gt;
53+
&lt;script src=&quot;{{ '/js/theme.js' | url }}&quot;&gt;&lt;/script&gt;
5354
&lt;/head&gt;
5455
&lt;body&gt;
5556
&lt;nav class=&quot;left&quot;&gt;
56-
{{ nav }}
57+
{{ nav.html }}
5758
&lt;/nav&gt;
5859
&lt;nav class=&quot;right&quot;&gt;
59-
{{ toc }}
60+
{{ page.toc }}
6061
&lt;/nav&gt;
6162
&lt;main&gt;
62-
{{ content }}
63-
{% include &quot;pagination.html&quot; %}
63+
{{ page.html }}
64+
{% if nav.previous or nav.next %}
65+
&lt;div class=&quot;pagination&quot;&gt;
66+
{% if nav.previous %}
67+
&lt;a class=&quot;previous&quot; href=&quot;{{ nav.previous.url }}&quot;&gt;← {{ nav.previous.title }}&lt;/a&gt;
68+
{% endif %}
69+
{% if nav.next %}
70+
&lt;a class=&quot;next&quot; href=&quot;{{ nav.next.url }}&quot;&gt;{{ nav.next.title }} →&lt;/a&gt;
71+
{% endif %}
72+
&lt;/div&gt;
73+
{% endif %}
6474
&lt;/main&gt;
6575
&lt;/body&gt;
6676
&lt;/html&gt;
6777
</code></pre>
68-
<p>The following templates are included in <a href="https://github.com/encode/mkdocs/blob/main/src/mkdocs/theme/">the default theme</a>...</p>
78+
<p>The following template is included in <a href="https://github.com/encode/mkdocs/blob/main/src/mkdocs/theme/">the default theme</a>...</p>
6979
<ul>
7080
<li><code>templates/base.html</code>- The base template used for rendering markdown pages.</li>
71-
<li><code>templates/favicon.svg</code> - an SVG used for the favicon, that displays the <code>config['site']['favicon']</code> emoji.</li>
72-
<li><code>templates/pagination.html</code> - Included by the base template. Renders next and previous page controls.</li>
7381
</ul>
74-
<h2 id="media"><a class="toclink" href="#media">Media</a></h2>
75-
<p>Any files that are not Markdown pages <code>*.md</code>, or templates <code>/templates/*</code>, are treated as media documents and are included in the website without modification.</p>
82+
<p>The following context is passed to the template rendering...</p>
83+
<table>
84+
<thead>
85+
<tr>
86+
<th><em>Variable</em></th>
87+
<th><em>Description</em></th>
88+
</tr>
89+
</thead>
90+
<tbody>
91+
<tr>
92+
<td><code>page</code></td>
93+
<td>The markdown page.</td>
94+
</tr>
95+
<tr>
96+
<td><code>page.html</code></td>
97+
<td>The page contents, rendered as HTML.</td>
98+
</tr>
99+
<tr>
100+
<td><code>page.text</code></td>
101+
<td>The text of the page, as markdown.</td>
102+
</tr>
103+
<tr>
104+
<td><code>page.path</code></td>
105+
<td>The path of the source file.</td>
106+
</tr>
107+
<tr>
108+
<td><code>page.url</code></td>
109+
<td>The URL from which the page is served.</td>
110+
</tr>
111+
<tr>
112+
<td><code>page.toc</code></td>
113+
<td>The table of contents for the page, as HTML.</td>
114+
</tr>
115+
<tr>
116+
<td><code>nav</code></td>
117+
<td>The site navigation.</td>
118+
</tr>
119+
<tr>
120+
<td><code>nav.html</code></td>
121+
<td>The site navigation, rendered into HTML.</td>
122+
</tr>
123+
<tr>
124+
<td><code>nav.previous</code></td>
125+
<td>The previous page, as configured in the nav.</td>
126+
</tr>
127+
<tr>
128+
<td><code>nav.previous.title</code></td>
129+
<td>The title of the previous page.</td>
130+
</tr>
131+
<tr>
132+
<td><code>nav.previous.url</code></td>
133+
<td>The url of the previous page.</td>
134+
</tr>
135+
<tr>
136+
<td><code>nav.next</code></td>
137+
<td>The next page, as configured in the nav.</td>
138+
</tr>
139+
<tr>
140+
<td><code>nav.next.title</code></td>
141+
<td>The title of the next page.</td>
142+
</tr>
143+
<tr>
144+
<td><code>nav.next.url</code></td>
145+
<td>The url of the next page.</td>
146+
</tr>
147+
<tr>
148+
<td><code>config</code></td>
149+
<td>The <code>mkdocs.toml</code> configuration.</td>
150+
</tr>
151+
</tbody>
152+
</table>
153+
<h2 id="pages"><a class="toclink" href="#pages">Pages</a></h2>
154+
<p>Any files ending with the <code>*.md</code> extension are treated as markdown pages, and rendered into HTML, then included in the base template.</p>
155+
<p>The following are treated as index pages...</p>
156+
<ul>
157+
<li><code>README.md</code> - Served as <code>/</code>.</li>
158+
<li><code>index.md</code> - Served as <code>/</code>.</li>
159+
</ul>
160+
<p>All other pages are lowercased, and served from a URL without the markdown extension...</p>
161+
<ul>
162+
<li><code>CONTRIBUTING.md</code> - Served as <code>/contributing/</code>.</li>
163+
</ul>
164+
<h2 id="statics"><a class="toclink" href="#statics">Statics</a></h2>
165+
<p>Any files that are not Markdown pages <code>*.md</code>, or templates <code>/templates/*</code>, are treated as static media and are included in the website without modification.</p>
76166
<p>This can include images, stylesheets, javascript, fonts, video and audio.</p>
77-
<p>The default theme includes the following media documents...</p>
167+
<p>The default theme includes the following static media...</p>
78168
<ul>
79169
<li><a href="../css/theme.css"><code>css/theme.css</code></a></li>
80170
<li><a href="../css/highlightjs.min.css"><code>css/highlightjs.min.css</code></a></li>
@@ -83,15 +173,14 @@ <h2 id="media"><a class="toclink" href="#media">Media</a></h2>
83173
<li><a href="../js/highlightjs.min.js"><code>js/highlightjs.min.js</code></a></li>
84174
<li><a href="../js/highlightjs-copy.min.js"><code>js/highlightjs-copy.min.js</code></a></li>
85175
</ul>
86-
<p>You can override these locally to style the color scheme, the typography &amp; layout, or to adapt the <code>highlight.js</code> code highlighting.</p>
87176

88-
<div class="pagination">
89-
90-
<a class="previous" href="../navigation/">← Site Navigation</a>
91-
92-
93-
</div>
94-
177+
<div class="pagination">
178+
179+
<a class="previous" href="../navigation/">← Site Navigation</a>
180+
181+
182+
</div>
183+
95184
</main>
96185
</body>
97186
</html>

‎writing/index.html‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
55
<title>MkDocs</title>
6-
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&#34;http://www.w3.org/2000/svg&#34; viewBox=&#34;0 0 100 100&#34;&gt;&lt;text y=&#34;.9em&#34; font-size=&#34;90&#34;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
6+
<link rel="icon" href="data:image/svg+xml,&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 100 100&quot;&gt;&lt;text y=&quot;.9em&quot; font-size=&quot;90&quot;&gt;📘&lt;/text&gt;&lt;/svg&gt;">
77
<link rel="stylesheet" href="../css/highlightjs.min.css">
88
<link rel="stylesheet" href="../css/highlightjs-copy.min.css">
99
<link rel="stylesheet" href="../css/theme.css">
@@ -242,15 +242,15 @@ <h2 id="task-list"><a class="toclink" href="#task-list">Task List</a></h2>
242242
</ol>
243243
</div>
244244

245-
<div class="pagination">
246-
247-
<a class="previous" href="../">← Introduction</a>
248-
249-
250-
<a class="next" href="../navigation/">Site Navigation →</a>
251-
252-
</div>
253-
245+
<div class="pagination">
246+
247+
<a class="previous" href="../">← Introduction</a>
248+
249+
250+
<a class="next" href="../navigation/">Site Navigation →</a>
251+
252+
</div>
253+
254254
</main>
255255
</body>
256256
</html>

0 commit comments

Comments
 (0)