Skip to content

Commit 5be49e2

Browse files
lovelydinosaurlovelydinosaur
committed
MkDocs refresh
0 parents  commit 5be49e2

25 files changed

Lines changed: 2287 additions & 0 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.pyc
2+
venv/
3+
site/

‎docs/index.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# MkDocs
2+
3+
MkDocs is a smart, simple website design tool using Markdown, templated HTML, and CSS.
4+
5+
## Installation
6+
7+
Install the mkdocs command line tool...
8+
9+
```shell
10+
$ pip install mkdocs
11+
```
12+
13+
## Getting started
14+
15+
1. Create a `README.md` file, and get authoring.
16+
2. Run `mkdocs serve` to view your documentation in a browser.
17+
3. Run `mkdocs build` to build a static website ready to host.
18+
19+
MkDocs supports [GitHub Flavored Markdown](writing.md) for page authoring.
20+
21+
## Adding pages
22+
23+
1. Create other markdown files, such as `CONTRIBUTING.md`.
24+
2. Link between your documents, eg. `See the [contributing](CONTRIBUTING.md) page for more details`.
25+
3. Create a `mkdocs.json` config file to add site navigation.
26+
27+
Sites can be single page, multipage, or deeply nested. Just use regular interlinking between your markdown documents, with `mkdocs.json` to define an overall [site layout](navigation.md).
28+
29+
## Custom styling
30+
31+
1. Create a `templates/base.html` file to customise the layout.
32+
2. Create a `css/base.css` file to override the default styles.
33+
3. Create a `js/base.css` file to override the default scripts.
34+
35+
Simple [styling adaptations](styling.md) include customising the colour scheme, the typography, or choosing the code highlighting style.

‎docs/navigation.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Site Navigation
2+
3+
Wang a load of different markdown files up there.
4+
5+
## Interlinking
6+
7+
Look just use relative file interlinking `[about](about.md)`.
8+
9+
## Navigation menu
10+
11+
Mush yourself up a navigation menu in the config.

‎docs/styling.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Styling
2+
3+
Styling is handled with HTML templating and regular web design.
4+
5+
## Templates
6+
7+
Markdown documents are rendered using Jinja templating.
8+
9+
The base template for rendering is `templates/base.html`:
10+
11+
```html
12+
<html>
13+
<head>
14+
<meta charset="utf-8">
15+
<title>{{ config['site']['title'] }}</title>
16+
<link rel="icon" href="/img/favicon.svg">
17+
<link rel="stylesheet" href="/css/highlightjs.min.css">
18+
<link rel="stylesheet" href="/css/theme.css">
19+
<script src="/js/highlightjs.min.js"></script>
20+
<script src="/js/theme.js"></script>
21+
</head>
22+
<body>
23+
<nav class="left">
24+
{{ nav }}
25+
</nav>
26+
<nav class="right">
27+
{{ toc }}
28+
</nav>
29+
<main>
30+
{{ content }}
31+
</main>
32+
</body>
33+
</html>
34+
```
35+
36+
You can override this template locally and adapt it to make layout changes.
37+
38+
## Media assets
39+
40+
The default theme includes the following assets:
41+
42+
* `css/theme.css` &mdash; *Copy and overide this file in order to change the color palette, the typography, or to other style changes.*
43+
* `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.*
44+
* `js/theme.js` &mdash; *Copy and override this file in order to add custom scripting.*
45+
* `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.*

‎docs/writing.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Writing Markdown
2+
3+
MkDocs deployed with Markdown, HTML & CSS.
4+
5+
Thanks for visiting [The Markdown Guide](https://www.markdownguide.org)!
6+
7+
This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every edge case, so if you need more information about any of these elements, refer to the reference guides for [basic syntax](https://www.markdownguide.org/basic-syntax/) and [extended syntax](https://www.markdownguide.org/extended-syntax/).
8+
9+
## Basic Syntax
10+
11+
These are the elements outlined in John Gruber’s original design document. All Markdown applications support these elements.
12+
13+
## Headings
14+
15+
# H1
16+
## H2
17+
### H3
18+
#### H4
19+
##### H5
20+
21+
## Ordered List
22+
23+
1. First item
24+
2. Second item
25+
3. Third item
26+
27+
## Unordered List
28+
29+
- First item
30+
- Second item
31+
- Third item
32+
33+
## Code
34+
35+
`code`
36+
37+
## Horizontal Rule
38+
39+
---
40+
41+
## Link
42+
43+
[About](ABOUT.md)
44+
45+
## Image
46+
47+
![calt text](img/codercat.jpg)
48+
49+
## Table
50+
51+
| Syntax | Description |
52+
| ----------- | ----------- |
53+
| Header | Title |
54+
| Paragraph | Text |
55+
56+
## Fenced Code Block
57+
58+
```json
59+
{
60+
"firstName": "John",
61+
"lastName": "Smith",
62+
"age": 25
63+
}
64+
```
65+
66+
## Blockquote
67+
68+
> Rumors of my death have been greatly exaggerated.
69+
70+
## Alerts
71+
72+
> [!NOTE]
73+
> Useful information that users should know, even when skimming content.
74+
75+
> [!TIP]
76+
> Helpful advice for doing things better or more easily.
77+
78+
> [!IMPORTANT]
79+
> Key information users need to know to achieve their goal.
80+
81+
> [!WARNING]
82+
> Urgent info that needs immediate user attention to avoid problems.
83+
84+
> [!CAUTION]
85+
> Advises about risks or negative outcomes of certain actions.
86+
87+
## Formatting
88+
89+
* **Bold text**
90+
* *Italic text*
91+
* ~~Strikethrough~~
92+
* <ins>Underlined</ins>
93+
* e <sup>i π</sup> = -1
94+
* H<sub>2</sub>O
95+
96+
## Footnotes
97+
98+
Here's a sentence with a footnote. [^1]
99+
100+
[^1]: This is the footnote.
101+
102+
## Emoji
103+
104+
`@octocat :+1: This PR looks great - it's ready to merge! :shipit:`
105+
106+
@octocat :+1: This PR looks great - it's ready to merge! :shipit:
107+
108+
### Task List
109+
110+
- [x] Write the press release
111+
- [ ] Update the website
112+
- [ ] Contact the media

‎mkdocs.toml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[mkdocs]
2+
version = 2
3+
4+
[site]
5+
title = "MkDocs"
6+
favicon = "📘"
7+
nav = [
8+
{title="Introduction", path="index.md"},
9+
{title="Writing markdown", path="writing.md"},
10+
{title="Site navigation", path="navigation.md"},
11+
{title="Styling your website", path="styling.md"}
12+
]

‎pyproject.toml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
[build-system]
2+
requires = ["hatchling"]
3+
build-backend = "hatchling.build"
4+
5+
[project]
6+
name = "mkdocs"
7+
description = "HTTP, for Python."
8+
requires-python = ">=3.10"
9+
authors = [
10+
{ name = "Tom Christie", email = "tom@tomchristie.com" },
11+
]
12+
classifiers = [
13+
"Development Status :: 4 - Beta",
14+
"Environment :: Web Environment",
15+
"Intended Audience :: Developers",
16+
"Operating System :: OS Independent",
17+
"Programming Language :: Python :: 3",
18+
"Programming Language :: Python :: 3.10",
19+
"Programming Language :: Python :: 3.11",
20+
"Programming Language :: Python :: 3.12",
21+
"Programming Language :: Python :: 3.13",
22+
"Topic :: Internet :: WWW/HTTP",
23+
]
24+
dependencies = [
25+
"httpx==1.0.dev3",
26+
"click",
27+
"jinja2",
28+
"markdown",
29+
"pymdown-extensions==10.16.1",
30+
"markdown-gfm-admonition==0.1.1",
31+
]
32+
dynamic = ["version"]
33+
34+
[tool.hatch.version]
35+
path = "src/mkdocs/__version__.py"
36+
37+
[project.scripts]
38+
mkdocs = "mkdocs:cli"

‎requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
-e .

‎src/mkdocs/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
from .mkdocs import MkDocs
2+
from .cli import cli
3+
4+
__all__ = [MkDocs, cli]

‎src/mkdocs/__main__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import mkdocs
2+
3+
4+
if __name__ == '__main__':
5+
mkdocs.cli()

0 commit comments

Comments
 (0)