iarv/mkdocs-quickstart
1
0
Fork 0
mirror of https://github.com/MichaelCurrin/mkdocs-quickstart.git synced 2026-03-28 17:42:47 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: Restructure and add content

Browse Source
This commit is contained in:
Michael Currin
2020-05-03 11:17:55 +02:00
parent 52a8f7862a
commit 2b4544320b
12 changed files with 298 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
.vscode/tasks.json vendored
View File

@@ -5,8 +5,9 @@
"tasks": [
{
"label": "build",
"type": "shell",
"command": "mkdocs build",
"type": "process",
"command": "${config:python.pythonPath}",
"args": ["-m", "mkdocs", "build"],
"problemMatcher": [],
"group": {
"kind": "build",
@@ -15,13 +16,36 @@
},
{
"label": "serve",
"type": "shell",
"command": "mkdocs serve"
"type": "process",
"command": "${config:python.pythonPath}",
"args": ["-m", "mkdocs", "serve"],
"problemMatcher": [],
},
{
"label": "deploy",
"type": "process",
"command": "${config:python.pythonPath}",
"args": ["-m", "mkdocs", "gh-deploy"],
"problemMatcher": [],
},
// Reference globally-installed MkDocs.
{
"label": "build-global",
"type": "shell",
"command": "mkdocs gh-deploy"
"command": "mkdocs build",
"problemMatcher": [],
},
{
"label": "serve-global",
"type": "shell",
"command": "mkdocs serve",
"problemMatcher": [],
},
{
"label": "deploy-global",
"type": "shell",
"command": "mkdocs gh-deploy",
"problemMatcher": [],
}
]
}

22
docs/about_mkdocs.md Normal file
View File

@@ -0,0 +1,22 @@
# About MkDocs
## Reasons to use MkDocs
- Create an elegant, modern docs site for your project.
- Create a static site and serve from Github Pages easily.
- Low-code solution
- No need to write HTML or learn templating syntax needed
- Use your existing markdown files as content
- Configure with a simple YAML file.
- Customizable.
- Add custom HTML if you want.
- Plugins available.
- Flexible theme choices.
- Includes search by default.
- Broken links to files (including from your navbar) will be detected at build time and shown as warnings.
## Do I need to know Python?
MkDocs is built in Python (like Sphynx), but you don't have to write Python code. If you setup a [Deploy](deloy) flow right, you don't even have to set it up locally, though then you can't preview.

52
docs/advanced.md Normal file
View File

@@ -0,0 +1,52 @@
# Advanced configuration
Once you've got the [Setup Project](setup_project.md) section, you can customize further using this guide. Or skip this and go to [Usage](usage.md).
## Navbar nesting
You can add an additional level to your navbar like this:
```yaml
nav:
- Home: index.md
- About: about.md
- Foo:
- Overview: foo/index.md
- Bar: foo/bar.md
```
However, adding a path when nesting as below is **invalid** and will give an error:
```yaml
nav:
- Home: index.md
- About: about.md
- Foo: foo/index.md
- Bar: foo/bar.md
```
See [issue #1139](https://github.com/mkdocs/mkdocs/issues/1139).
## Add config options
See [Configuration](https://www.mkdocs.org/user-guide/configuration/) page on MkDocs site for options.
## Separate docs directory approach
You can also structure your project to have the setup above nested inside a `docs` directory. This is useful you have a few other directories and you want to keep the project root clean.
- `docs/`
- `docs/`
- `index.md`
- `theme/`
- `main.html`
- `nav.html`
- `toc.html`
- `mkdocs.yml`
An example of this is the [Poetry](https://github.com/python-poetry/poetry/tree/master/docs) repo. That project is also how I got into MkDocs in the first place.

2
docs/deploy.md
View File

@@ -1,5 +1,5 @@
# Deploy
> How to deploy a MkDocs site to be served publically
> Build and deploy to a remote public site
See [Deploying Your Docs](https://www.mkdocs.org/user-guide/deploying-your-docs/) on the Mkdocs site for more details.

28
docs/index.md
View File

@@ -2,26 +2,20 @@
> A concise recipe for setting up a MkDocs docs site on Github Pages
This is based on the [mkdocs.org](https://www.mkdocs.org/) tutorial.
Use the MkDocs (make docs) tool to create build a docs site around markdown docs. Add to an existing project or create a project from scratch.
## Features of this project
- Quickstart tutorial
- Live demo on Github Pages
- Template repo
## Features
> How to use this project
- **Tutorial**
- Covering installation, setting up and configuring project, running it locally and deploying it.
- **Template repo**
- Click *Use this Template* on Github.
- **Live demo**
- Hosted on Github Pages.
The aim here is not be complete or explain all concepts. It is to provide a reference for common steps and choices needed when setting up a docs site, but still at a beginner-friendly level.
## Reasons to use MdDocs
- Create an elegant, modern docs site for your project.
- Create a static site and serve from Github Pages easily.
- Flexible theming.
- No coding in HTML or templating langauge needed - use your existing markdown files and a YAML config.
- Customizable.
- Plugins available.
- Includes search by default.
MkDocs is built in Python (like Sphynx) but you don't have to write Python code. If you setup a [Deploy](deloy) flow right, you don't even have to set it up locally, though then you can't preview.
This guide is based on the [mkdocs.org](https://www.mkdocs.org/) tutorial.

58
docs/installation.md Normal file
View File

@@ -0,0 +1,58 @@
# Installation
> How to install MkDocs locally.
## Requirements
- [Python](https://www.python.org/)
## Install system dependencies
<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
## Setup repo
Choose or setup a MkDocs project.
- Follow the tutorial page to setup a project.
- Or click _Use this template_ on this repo to create your own copy of the repo, then clone it.
## Install project dependencies
> Install MkDocs
For more info, see the [Installation](https://www.mkdocs.org/#installation) page on the MkDocs site.
### Use a virtual environment
Create a virtual environment at the project root.
```sh
python3 -m venv venv
```
Activate it.
```
source venv/bin/activate
```
Install dependencies.
```sh
pip install mkdocs
```
### Globally
If you prefer to install MkDocs once and reuse it across projects, you can install it globally.
MkDocs is available with package managers like `apt-get`, `homebrew` and `yum`.
You can install like this too:
```sh
python3 -m pip install mkdocs
```

60
docs/setup_and_run.md
View File

@@ -1,60 +0,0 @@
# Inst and run
> How to setup and run a docs site locally
## Install
Make sure you have Python installed - ideally a recent Python 3 version.
Choose or setup a MkDocs project.
- Follow the tutorial page to setup a project.
- Or click _Use this template_ on this repo to create your own copy of the repo, then clone it.
Create a virtual environment at the project root.
```sh
python3 -m venv venv
```
Install dependencies.
```sh
pip install mkdocs
```
## Usage
_Note: If using VS Code, you can use the command palette instead to run the configured tasks - these are setup in `.vscode/tasks.json`._
### Server docs locally
This will build the docs in memory (not to disk) and serve an auto-reloading server.
```sh
mkdocs serve
```
Open URL:
- [localhost:8000](http://localhost:8000)
### Build docs
Build docs site to `site` directory. Useful for production build or simulating that locally.
```sh
mkdocs build
```
Add this flag to remove stale files when building.
```sh
mkdocs build --clean
```

76
docs/setup_project.md Normal file
View File

@@ -0,0 +1,76 @@
# Setup project
> How to create a MkDocs site from scratch
This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
## How to use this guide
Use one of the approaches below:
- Create a quickstart project with the `new` command covered in [Create a starter site](#create-a-starter-site).
- Follow the extended guide to create a [Setup up docs site](#setup-a-docs-site) by hand.
- Click *Use this Template* button on the Github repo to get your own copy.
### Basic structure
This is the simplest MkDocs site you can make:
- `docs/`
- `index.md` - Homepage in the `docs` directory (by default).
- `mkdocs.yml` - Config at the root.
### Create a starter site
Run this command to create the starter site outline above. This make the steps below go quicker.
```sh
cd my-project
mkdocs new PATH
```
### Setup a docs site
_Tip: Optionally use the `new` command covered above to setup the config and index page first and then continue_.
1. Create doc pages.
1. Create a `docs` directory.
2. Create `index.md` as your homepage.
3. Create other markdown pages (optional).
- Use placeholder content if you want to move on and then come back to expand them.
- If you have any existing markdown docs, these will work too.
2. Setup config.
1. Create `mkdocs.yml` at project root.
2. Setup navbar there. e.g.
```yaml
nav:
- Home: index.md
- About: about.md
```
3. Choose a theme. e.g.
```yaml
theme: readthedocs
```
3. Create a favicon (optional).
- It will be picked up at this path: `docs/img/favicon.ico`.
4. Add to your `.gitignore`.
- Add build directory. This will prevent it from being versioned on `master` branch.
- Add virtual environment, if using one.
- e.g.
```
site/
venv
```
You project should now look this this:
- `docs/`
- `index.md`
- Other pages...
- `mkdocs.yml`
- `.gitignore`
- `venv`

8
docs/tldr.md Normal file
View File

@@ -0,0 +1,8 @@
## TL;DR
> A simplified version of the tutorial.
1. `pip install mkdocs`
2. `mkdocs new .` or click _Use this Template_
3. `mkdocs serve`
4. `mkdocs gh-deploy`
5. View published site at [https://USERNAME.github.io/REPO-NAME/]()

58
docs/tutorial.md
View File

@@ -1,58 +0,0 @@
# Tutorial
> How to create a MkDocs site
This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
### Basic structure
This is the simplest MkDocs site you can make:
- `mkdocs.yml` - Config at the root.
- `docs/index.md` - Homepage in the `docs` directory (by default).
The steps below start with that and extend it to more pages.
Run this command to create the starter site above. This make the steps below go quicker.
```sh
cd my-project
mkdocs new PATH
```
### Setup site
1. Create docs pages.
1. Create `docs` directory.
2. Create `index.md`
3. Create other pages (optional).
2. Setup config.
1. Create `mkdocs.yml` at project root.
2. Setup navbar there. e.g.
```yaml
nav:
- Home: index.md
- About: about.md
```
3. Choose a theme. e.g.
```yaml
theme: readthedocs
```
3. Create a favicon (optional).
- It will be picked up at this path: `docs/img/favicon.ico`.
4. Add to your `.gitignore`.
- Add build directory. This will prevent it from being versioned on `master` branch.
- Add virtual environment, if using one.
- e.g.
```
site/
venv
```
### Further configuration
See [Configuration](https://www.mkdocs.org/user-guide/configuration/) page on MkDocs site for options.

33
docs/usage.md Normal file
View File

@@ -0,0 +1,33 @@
# Usage
> Build and preview a site locally
_Note: If using VS Code, you can use the command palette instead to run the configured tasks - these are setup in `.vscode/tasks.json`._
## Serve docs
This will build the docs in memory (not to disk) and serve an auto-reloading server.
```sh
mkdocs serve
```
Open URL:
- [localhost:8000](http://localhost:8000)
## Build docs
Build docs site to `site` directory. Useful for production build or simulating that locally.
```sh
mkdocs build
```
Add this flag to remove stale files when building.
```sh
mkdocs build --clean
```

11
mkdocs.yml
View File

@@ -3,9 +3,14 @@ site_name: MkDocs Quickstart
site_description: 'A concise recipe for setting up a MkDocs docs site on Github Pages'
nav:
- Home: index.md
- Setup and run: setup_and_run.md
- Tutorial: tutorial.md
- Deploy: deploy.md
- About MkDocs: about_mkdocs.md
- Tutorial:
- TL;DR: tldr.md
- Installation: installation.md
- Setup project: setup_project.md
- Advanced configuration: advanced.md
- Usage: usage.md
- Deploy: deploy.md
theme: readthedocs
# For adding Edit in Github button.
repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart/