adam/mkdocs-quickstart
1
0
Fork 0
mirror of https://github.com/MichaelCurrin/mkdocs-quickstart.git synced 2026-06-25 04:22:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore: Move to docs directory

Browse Source
This commit is contained in:
Michael Currin
2020-10-17 17:00:45 +02:00
parent a028e5c228
commit 99fb0757c7
11 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs/about-mkdocs.md
+40
View File
@@ -0,0 +1,40 @@
# About MkDocs
## What is MkDocs?
The description on the MkDocs site is:
> Project documentation with Markdown.
MkDocs is a Python tool that generates a static site based on content written in Markdown.
If you are new to markdown, see the [Getting Started](https://www.markdownguide.org/getting-started/) page on the Markdown Guide website.
## Resources
- [mkdocs.org](https://www.mkdocs.org) homepage
- [mkdocs/mkdocs ![Repo stars](https://img.shields.io/github/stars/mkdocs/mkdocs?style=social)](https://github.com/mkdocs/mkdocs)
- [MkDocs Wiki](https://github.com/mkdocs/mkdocs/wiki) - covering themes, plugins, recipes and more.
## 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 Sphinx), but you don't have to write Python code. If you setup a [Deploy](deploy) flow right, you don't even have to set it up locally, though then you can't preview.
docs/docs/index.md
+27
View File
@@ -0,0 +1,27 @@
# MkDocs Quickstart
> A template, live demo and tutorial for how to setup a MkDocs docs site on GitHub Pages
[![Repo stars](https://img.shields.io/github/stars/MichaelCurrin/mkdocs-quickstart?style=social)](https://github.com/MichaelCurrin/mkdocs-quickstart)
Use the MkDocs (make docs) tool to create build a docs site around markdown docs.
Follow the tutorial to add an existing project or create a project from scratch. The result will look like this project.
## Features
> How to use this project
- **Follow the tutorial instructions**
- Install and configure a new or existing project.
- Run it locally.
- Deploy it.
- **Add a copy of this project to your repos**
- [![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
- **View the live demo**
- This site is hosted on GitHub Pages. See if you like it. Other themes are available - see the tutorial.
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.
This guide is based on the [mkdocs.org](https://www.mkdocs.org/) tutorial.
docs/docs/tutorial/advanced.md
+53
View File
@@ -0,0 +1,53 @@
# Advanced
> Beyond the basic configuration and content
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
```
The value can either be a string (as in the first case) or a map (as in the last case). This seems to be a YAML limitation but see also [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.
## Embedding
To embed a gist, just copy and paste the embed script URL which is provided on a gist.
e.g.
```html
<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
```
docs/docs/tutorial/deploy.md
+64
View File
@@ -0,0 +1,64 @@
# Deploy
> 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.
## GitHub Pages
> How to deploy your docs site to GitHub Pages.
Follow one of the approaches below:
- [Run deploy command](#run-deploy-command) - Run a MkDocs CLI command locally to deploy.
- [Deploy with Githhub Actions](#deploy-with-github-actions) - Setup continous deployment config to enable deploys on a change to files on GitHub.
_Note this is for a Project Page on a subpath and not an Organization or User Page._
### Run deploy command
> Run a MkDocs CLI command locally to deploy
MkDocs needs to know where to publish commits on GitHub - so make sure you are working with a repo that you cloned, or that you initialize the local repo and add a `remote` repo.
Run this command locally:
```sh
$ make d
```
That will use `Makefile` to run the following:
```sh
$ mkdocs gh-deploy --strict
```
That will do the following:
1. Clean and build to `site` directory.
2. Push to `gh-pages` branch. Note: You must not edit this branch directly.
3. Enable GitHub Pages if it was not yet enabled
Then go to your repo on GitHub, see the *environment* tab and click _View deployment_.
e.g.
- [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
See deploy options:
```sh
$ mkdocs gh-deploy --help
```
### Deploy with GitHub Actions
> Setup continuous deployment config to enable deploys on a change to files on GitHub
When you make changes to your docs config or the docs directory, especially editing on GitHub directly, it's often useful to have the docs site build and deploy automatically in a remote environment. This is provided for free by GitHub.
This action is setup to do that for MkDocs and the Material theme:
- [deploy-mkdocs](https://github.com/marketplace/actions/deploy-mkdocs) action in marketplace.
See this implemented in the [workflow](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/.github/workflows/docs.yml) file of this MkDocs Quickstart project.
docs/docs/tutorial/installation.md
+59
View File
@@ -0,0 +1,59 @@
# Installation
> How to install MkDocs locally.
## Requirements
- [Python 3](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 locally
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.
```sh
$ source venv/bin/activate
```
Install `mkdocs` from project dependencies list.
```sh
$ pip install -r requirements.txt
```
### Install globally
If you prefer to install MkDocs once and reuse it across projects, then you can install it globally.
MkDocs is available using package managers like `apt-get`, `homebrew` and `yum`.
You can install like this too:
```sh
python3 -m pip install mkdocs
```
docs/docs/tutorial/setup-project.md
+142
View File
@@ -0,0 +1,142 @@
# 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.
### 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.
### Requirements file
A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure `pip install mkdocs` and `pip install THEME` lines are your instructions.
If you want to add, then include `requirements.txt` at the root. If your project is already a Python project, you might prefer to add `mkdocs` in `requirements-dev.txt` or at `docs/requirements.txt` to keep it isolated.This file should have `mkdocs` in it and also any themes if needed.
### Create a starter site
Run this command to create a starter site. This make the steps below go quicker.
```sh
cd my-project
mkdocs new PATH
```
The result will be same as the [Basic structure](#basic-structure) defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's [new.py](https://github.com/mkdocs/mkdocs/blob/master/mkdocs/commands/new.py) module.
### 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 a navbar there.
3. Choose a theme.
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.
You project should now look this this:
- `docs/`
- `index.md`
- Other pages...
- `mkdocs.yml`
- `.gitignore`
- `venv`
- `requirements.txt` - optional
## Sample content
### Ignore file
`.gitignore`
```
site/
venv
```
### Navbar
```yaml
nav:
- Home: index.md
- About: about.md
```
### Themes
#### Builtin
Use a builtin theme that comes with MkDocs.
The default.
```yaml
theme: mkdocs
```
Using ReadTheDocs theme and alternative config syntax.
```yaml
theme:
name: readthedocs
```
Find more [supported themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). If it doesn't immediately, you'll have to use `pip` to install it and add to a `requirements.txt` file.
#### ReadTheDocs Dropdown theme
See below using [mkdocs-rtd-dropdown](https://github.com/cjsheets/mkdocs-rtd-dropdown).
`requirements.txt`
```
mkdocs-rtd-dropdown
```
`mkdocs.yml`
```yaml
theme:
name: 'rtd-dropdown'
```
### Material for MkdDocs theme
See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Setup page for config options.
`requirements.txt`
```
mkdocs-material-extensions>=1.0
```
`mkdocs.yml`
```yaml
theme:
name: 'material'
```
docs/docs/tutorial/tldr.md
+28
View File
@@ -0,0 +1,28 @@
# TL;DR
> A simplified version of the tutorial.
## Local setup
1. [Install](installation.md)
- `pip install mkdocs`
2. [Setup project](setup-project.md)
- `mkdocs new .` or [![Use this template](https://img.shields.io/badge/Use_this_template-green.svg)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
3. [Run](usage.md)
- `mkdocs serve`
4. View on [http://localhost:8000](http://localhost:8000)
## Deploy to remote site
### Run deploy command locally
1. [Deploy](deploy.md) to GitHub Pages
- `mkdocs gh-deploy`
2. View published site on GitHub Pages at `https://USERNAME.github.io/REPO-NAME/`
### Run continuous integration
For CI/CD deploy, use GitHub Actions with an action such as [Deploy MkDocs](https://github.com/marketplace/actions/deploy-mkdocs). Or use Netlify.
This is not covered in this tutorial.
docs/docs/tutorial/usage.md
+36
View File
@@ -0,0 +1,36 @@
# Usage
> Build and preview a site locally
## Serve docs
This will build the docs in memory (not to disk) and serve an auto-reloading server.
```sh
$ make s
```
That will use `Makefile` to run the following:
```sh
$ mkdocs serve --strict
```
Then open in your browser:
- [localhost:8000](http://localhost:8000)
## Build docs
Build docs site to `site` directory. This is useful for a CI flow.
```sh
$ make b
```
That will use `Makefile` to run the following:
```sh
$ mkdocs build --strict
```