Skip to content

Commit af74932

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

7 files changed

Lines changed: 151 additions & 75 deletions

File tree

‎configuration/index.html‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
5-
<title>MkDocs</title>
5+
<title>Configuration</title>
66
<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">
@@ -16,8 +16,9 @@
1616
<ul>
1717
<li><a href="../">Introduction</a></li>
1818
<li><a href="../writing/">Writing Markdown</a></li>
19-
<li><a href="../navigation/">Site Navigation</a></li>
19+
<li><a href="../navigation/">Interlinking &amp; Navigation</a></li>
2020
<li><a href="../styling/">HTML Styling</a></li>
21+
<li><a href="../roadmap/">Roadmap</a></li>
2122
</ul>
2223
</nav>
2324
<nav class="right">

‎css/theme.css‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ h1, h2, h3, h4, h5 {
104104
}
105105

106106
h1 { font-size: 2rem; }
107-
h2 { font-size: 1.5rem; }
107+
h2 { font-size: 1.5rem; margin-top: 3.5rem; }
108108
h3 { font-size: 1.25rem; }
109109
h4 { font-size: 1rem; }
110110

‎index.html‎

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
5-
<title>MkDocs</title>
5+
<title>Introduction</title>
66
<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">
@@ -16,8 +16,9 @@
1616
<ul>
1717
<li><a class="active" href=".">Introduction</a></li>
1818
<li><a href="writing/">Writing Markdown</a></li>
19-
<li><a href="navigation/">Site Navigation</a></li>
19+
<li><a href="navigation/">Interlinking &amp; Navigation</a></li>
2020
<li><a href="styling/">HTML Styling</a></li>
21+
<li><a href="roadmap/">Roadmap</a></li>
2122
</ul>
2223
</nav>
2324
<nav class="right">
@@ -37,30 +38,37 @@
3738
<main>
3839
<h1 id="mkdocs"><a class="toclink" href="#mkdocs">MkDocs</a></h1>
3940
<p>MkDocs is a smart, simple, website design tool.</p>
41+
<p>Documentation available at... <a href="https://www.encode.io/mkdocs/">https://www.encode.io/mkdocs/</a></p>
4042
<h2 id="installation"><a class="toclink" href="#installation">Installation</a></h2>
4143
<p>Install the <code>mkdocs</code> command line tool...</p>
42-
<pre><code class="language-shell">$ pip install mkdocs
44+
<pre><code class="language-shell">$ pip install git+https://github.com/encode/mkdocs.git
4345
</code></pre>
46+
<p>This will install the <em><a href="roadmap/">version 2.0 prelease</a></em>.</p>
4447
<h2 id="getting-started"><a class="toclink" href="#getting-started">Getting started</a></h2>
45-
<ol>
46-
<li>Create a <code>README.md</code> page.</li>
47-
<li>Run <code>mkdocs serve</code> to view your documentation in a browser.</li>
48-
<li>Run <code>mkdocs build</code> to build a static website ready to host.</li>
49-
</ol>
50-
<p>MkDocs supports <a href="writing/">GitHub Flavored Markdown</a> for page authoring.</p>
48+
<p>Create a <code>mkdocs.toml</code> config file.</p>
49+
<pre><code class="language-toml">[mkdocs]
50+
nav = [
51+
{title=&quot;Homepage&quot;, path=&quot;README.md&quot;},
52+
]
53+
</code></pre>
54+
<p>Create a <code>docs/README.md</code> page. <em>MkDocs supports <a href="writing/">GitHub Flavored Markdown</a> for page authoring.</em></p>
55+
<pre><code class="language-markdown"># MkDocs
56+
57+
Let's get writing.
58+
</code></pre>
59+
<p>Run <code>mkdocs serve</code> to view your documentation in a browser.</p>
5160
<h2 id="adding-pages"><a class="toclink" href="#adding-pages">Adding pages</a></h2>
5261
<ol>
5362
<li>Create additional markdown pages.</li>
54-
<li>Use markdown interlinking between pages.</li>
55-
<li>Create a <code>mkdocs.toml</code> config file to define the site navigation.</li>
63+
<li>Use <a href="navigation/#interlinking">markdown interlinking</a> between pages.</li>
64+
<li>Edit the <code>mkdocs.toml</code> config file to define <a href="navigation/#navigation">the site navigation</a>.</li>
5665
</ol>
5766
<h2 id="custom-styling"><a class="toclink" href="#custom-styling">Custom styling</a></h2>
67+
<p>Styling adaptations can be kept simple, such as customising the colour scheme, or more comprehensive, such as creating an entirely new theme.</p>
5868
<ol>
59-
<li>Create a <code>templates/base.html</code> file to customise the layout.</li>
60-
<li>Create a <code>css/base.css</code> file to override the default styles.</li>
61-
<li>Create a <code>js/base.css</code> file to override the default scripts.</li>
69+
<li>Modify <a href="styling/#templates">the HTML templating</a> to customise the layout.</li>
70+
<li>Override or add <a href="styling/#statics">CSS and JavaScript</a> static assets.</li>
6271
</ol>
63-
<p>Simple <a href="styling/">styling adaptations</a> include customising the colour scheme, the typography, or choosing the code highlighting style.</p>
6472

6573
<div class="pagination">
6674

‎navigation/index.html‎

Lines changed: 56 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
5-
<title>MkDocs</title>
5+
<title>Interlinking & Navigation</title>
66
<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">
@@ -16,71 +16,44 @@
1616
<ul>
1717
<li><a href="../">Introduction</a></li>
1818
<li><a href="../writing/">Writing Markdown</a></li>
19-
<li><a class="active" href=".">Site Navigation</a></li>
19+
<li><a class="active" href=".">Interlinking &amp; Navigation</a></li>
2020
<li><a href="../styling/">HTML Styling</a></li>
21+
<li><a href="../roadmap/">Roadmap</a></li>
2122
</ul>
2223
</nav>
2324
<nav class="right">
2425
<div class="toc">
2526
<ul>
26-
<li><a href="#site-navigation">Site Navigation</a><ul>
27+
<li><a href="#interlinking-navigation">Interlinking &amp; Navigation</a><ul>
2728
<li><a href="#interlinking">Interlinking</a></li>
28-
<li><a href="#configuration">Configuration</a></li>
29+
<li><a href="#navigation">Navigation</a></li>
30+
<li><a href="#url-structure">URL Structure</a></li>
2931
</ul>
3032
</li>
3133
</ul>
3234
</div>
3335

3436
</nav>
3537
<main>
36-
<h1 id="site-navigation"><a class="toclink" href="#site-navigation">Site Navigation</a></h1>
37-
<p>When building sites with multiple pages, use <code>index.md</code> or <code>README.md</code> for root URLs.</p>
38-
<table>
39-
<thead>
40-
<tr>
41-
<th><strong>File</strong></th>
42-
<th><strong>URL</strong></th>
43-
</tr>
44-
</thead>
45-
<tbody>
46-
<tr>
47-
<td><code>index.md</code></td>
48-
<td><code>/</code></td>
49-
</tr>
50-
<tr>
51-
<td><code>markdown.md</code></td>
52-
<td><code>/markdown/</code></td>
53-
</tr>
54-
<tr>
55-
<td><code>navigation.md</code></td>
56-
<td><code>/navigation/</code></td>
57-
</tr>
58-
<tr>
59-
<td><code>styling.md</code></td>
60-
<td><code>/styling/</code></td>
61-
</tr>
62-
</tbody>
63-
</table>
64-
<p>Pages should use the <code>.md</code> file extension in order to be rendered as markdown. Other documents are served unmodified as <a href="../styling/#media">media files</a>.</p>
38+
<h1 id="interlinking-navigation"><a class="toclink" href="#interlinking-navigation">Interlinking &amp; Navigation</a></h1>
39+
<p>Navigation within your documentation is handled by using <a href="#interlinking">document interlinking</a>, and optional <a href="#navigation">site-wide navigation</a>.</p>
6540
<h2 id="interlinking"><a class="toclink" href="#interlinking">Interlinking</a></h2>
66-
<p>Use relative interlinking to help users navigate between documents.</p>
67-
<p>Link to another markdown file in the same directory&hellip;</p>
41+
<p>Use relative markdown links to allow users to navigate between documents.</p>
42+
<p>For example, a website with <code>README.md</code> and <code>CONTRIBUTING.md</code> pages, might include the following&hellip;</p>
6843
<pre><code class="language-markdown">See our [contribution documentation](CONTRIBUTING.md) for more details on getting involved.
6944
</code></pre>
70-
<p>Link to a document in a subdirectory&hellip;</p>
45+
<p>If your site includes pages within a directory structure, the page interlinking might include navigation between directories.</p>
46+
<p>For example, a link from <code>index.md</code> to <code>tutorial/getting-started.md</code>&hellip;</p>
7147
<pre><code class="language-markdown">The [tutorial](tutorial/getting-started.md) will help get you started.
7248
</code></pre>
73-
<p>Link to a document in a parent directory&hellip;</p>
49+
<p>And a corresponding link from <code>tutorial/getting-started.md</code> back to <code>index.md</code>&hellip;</p>
7450
<pre><code class="language-markdown">Back to the [homepage](../index.md).
7551
</code></pre>
76-
<h2 id="configuration"><a class="toclink" href="#configuration">Configuration</a></h2>
52+
<p>Links can either use the markdown inline style, as above, or the reference style.</p>
53+
<h2 id="navigation"><a class="toclink" href="#navigation">Navigation</a></h2>
7754
<p>You can include site-wide navigation by using the <code>mkdocs.toml</code> configuration.</p>
55+
<p>This is typically used by the HTML styling to include a navigation menu.</p>
7856
<pre><code class="language-toml">[mkdocs]
79-
version = 2
80-
81-
[site]
82-
title = &quot;MkDocs&quot;
83-
favicon = &quot;📘&quot;
8457
nav = [
8558
{title=&quot;Introduction&quot;, path=&quot;index.md&quot;},
8659
{title=&quot;Writing Markdown&quot;, path=&quot;markdown.md&quot;},
@@ -91,11 +64,6 @@ <h2 id="configuration"><a class="toclink" href="#configuration">Configuration</a
9164
<p>This allows the theme to display navigation controls, as well as including <code>← previous</code> and <code>next →</code> links.</p>
9265
<p>The navigation configuration can also include nested elements.</p>
9366
<pre><code class="language-toml">[mkdocs]
94-
version = 2
95-
96-
[site]
97-
title = &quot;MkDocs&quot;
98-
favicon = &quot;📘&quot;
9967
nav = [
10068
{title=&quot;Introduction&quot;, path=&quot;index.md&quot;},
10169
{title=&quot;Tutorial&quot;, children=[
@@ -110,6 +78,46 @@ <h2 id="configuration"><a class="toclink" href="#configuration">Configuration</a
11078
]}
11179
]
11280
</code></pre>
81+
<h2 id="url-structure"><a class="toclink" href="#url-structure">URL Structure</a></h2>
82+
<p>Ensuring your website has a clean, meaningful URL structure is important for navigation.</p>
83+
<ul>
84+
<li>Markdown pages are lowercased.</li>
85+
<li>The file extension is not included in the URL.</li>
86+
<li>Use either <code>index.md</code> or <code>README.md</code> for root URLs.</li>
87+
</ul>
88+
<p>Some examples...</p>
89+
<table>
90+
<thead>
91+
<tr>
92+
<th><strong>Markdown Page</strong></th>
93+
<th><strong>HTML output</strong></th>
94+
<th><strong>URL</strong></th>
95+
</tr>
96+
</thead>
97+
<tbody>
98+
<tr>
99+
<td><code>index.md</code></td>
100+
<td><code>index.html</code></td>
101+
<td><code>/</code></td>
102+
</tr>
103+
<tr>
104+
<td><code>markdown.md</code></td>
105+
<td><code>/markdown/index.html</code></td>
106+
<td><code>/markdown/</code></td>
107+
</tr>
108+
<tr>
109+
<td><code>navigation.md</code></td>
110+
<td><code>/navigation/index.html</code></td>
111+
<td><code>/navigation/</code></td>
112+
</tr>
113+
<tr>
114+
<td><code>styling.md</code></td>
115+
<td><code>/styling/index.html</code></td>
116+
<td><code>/styling/</code></td>
117+
</tr>
118+
</tbody>
119+
</table>
120+
<p><br/></p>
113121

114122
<div class="pagination">
115123

‎roadmap/index.html‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<html>
2+
<head>
3+
<meta charset="utf-8">
4+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
5+
<title>Roadmap</title>
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;">
7+
<link rel="stylesheet" href="../css/highlightjs.min.css">
8+
<link rel="stylesheet" href="../css/highlightjs-copy.min.css">
9+
<link rel="stylesheet" href="../css/theme.css">
10+
<script src="../js/highlightjs.min.js"></script>
11+
<script src="../js/highlightjs-copy.min.js"></script>
12+
<script src="../js/theme.js"></script>
13+
</head>
14+
<body>
15+
<nav class="left">
16+
<ul>
17+
<li><a href="../">Introduction</a></li>
18+
<li><a href="../writing/">Writing Markdown</a></li>
19+
<li><a href="../navigation/">Interlinking &amp; Navigation</a></li>
20+
<li><a href="../styling/">HTML Styling</a></li>
21+
<li><a class="active" href=".">Roadmap</a></li>
22+
</ul>
23+
</nav>
24+
<nav class="right">
25+
<div class="toc">
26+
<ul>
27+
<li><a href="#roadmap">Roadmap</a></li>
28+
</ul>
29+
</div>
30+
31+
</nav>
32+
<main>
33+
<h1 id="roadmap"><a class="toclink" href="#roadmap">Roadmap</a></h1>
34+
<p>This is the version 2.0 prelease, currently in-progress.</p>
35+
<ul>
36+
<li>Authoring &amp; distributing themes.</li>
37+
<li>Managing search &amp; search indexes.</li>
38+
<li>Configuration.</li>
39+
<li>Build out the shortcodes functionality.</li>
40+
</ul>
41+
42+
<div class="pagination">
43+
44+
<a class="previous" href="../styling/">← HTML Styling</a>
45+
46+
47+
</div>
48+
49+
</main>
50+
</body>
51+
</html>

‎styling/index.html‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
5-
<title>MkDocs</title>
5+
<title>HTML Styling</title>
66
<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">
@@ -16,8 +16,9 @@
1616
<ul>
1717
<li><a href="../">Introduction</a></li>
1818
<li><a href="../writing/">Writing Markdown</a></li>
19-
<li><a href="../navigation/">Site Navigation</a></li>
19+
<li><a href="../navigation/">Interlinking &amp; Navigation</a></li>
2020
<li><a class="active" href=".">HTML Styling</a></li>
21+
<li><a href="../roadmap/">Roadmap</a></li>
2122
</ul>
2223
</nav>
2324
<nav class="right">
@@ -43,8 +44,8 @@ <h2 id="templates"><a class="toclink" href="#templates">Templates</a></h2>
4344
&lt;head&gt;
4445
&lt;meta charset=&quot;utf-8&quot;&gt;
4546
&lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1.0&quot;&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;
47+
&lt;title&gt;{{ config.mkdocs.title or page.title }}&lt;/title&gt;
48+
&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.mkdocs.favicon or '📘' }}&amp;lt;/text&amp;gt;&amp;lt;/svg&amp;gt;&quot;&gt;
4849
&lt;link rel=&quot;stylesheet&quot; href=&quot;{{ '/css/highlightjs.min.css' | url }}&quot;&gt;
4950
&lt;link rel=&quot;stylesheet&quot; href=&quot;{{ '/css/highlightjs-copy.min.css' | url }}&quot;&gt;
5051
&lt;link rel=&quot;stylesheet&quot; href=&quot;{{ '/css/theme.css' | url }}&quot;&gt;
@@ -113,6 +114,10 @@ <h2 id="templates"><a class="toclink" href="#templates">Templates</a></h2>
113114
<td>The table of contents for the page, as HTML.</td>
114115
</tr>
115116
<tr>
117+
<td><code>page.title</code></td>
118+
<td>The first heading in the table of contents.</td>
119+
</tr>
120+
<tr>
116121
<td><code>nav</code></td>
117122
<td>The site navigation.</td>
118123
</tr>
@@ -176,8 +181,10 @@ <h2 id="statics"><a class="toclink" href="#statics">Statics</a></h2>
176181

177182
<div class="pagination">
178183

179-
<a class="previous" href="../navigation/">← Site Navigation</a>
184+
<a class="previous" href="../navigation/">← Interlinking & Navigation</a>
185+
180186

187+
<a class="next" href="../roadmap/">Roadmap →</a>
181188

182189
</div>
183190

‎writing/index.html‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33
<meta charset="utf-8">
44
<meta name="viewport" content="width=device-width, initial-scale=1.0">
5-
<title>MkDocs</title>
5+
<title>Writing Markdown</title>
66
<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">
@@ -16,8 +16,9 @@
1616
<ul>
1717
<li><a href="../">Introduction</a></li>
1818
<li><a class="active" href=".">Writing Markdown</a></li>
19-
<li><a href="../navigation/">Site Navigation</a></li>
19+
<li><a href="../navigation/">Interlinking &amp; Navigation</a></li>
2020
<li><a href="../styling/">HTML Styling</a></li>
21+
<li><a href="../roadmap/">Roadmap</a></li>
2122
</ul>
2223
</nav>
2324
<nav class="right">
@@ -60,7 +61,7 @@ <h2 id="headings"><a class="toclink" href="#headings">Headings</a></h2>
6061
##### H5
6162
</code></pre>
6263
<h1>H1</h1>
63-
<h2>H2</h2>
64+
<h2 style="margin-top: 1.5rem">H2</h2>
6465
<h3>H3</h3>
6566
<h4>H4</h4>
6667
<h5>H5</h5>
@@ -247,7 +248,7 @@ <h2 id="task-list"><a class="toclink" href="#task-list">Task List</a></h2>
247248
<a class="previous" href="../">← Introduction</a>
248249

249250

250-
<a class="next" href="../navigation/">Site Navigation →</a>
251+
<a class="next" href="../navigation/">Interlinking & Navigation →</a>
251252

252253
</div>
253254

0 commit comments

Comments
 (0)