feat: rename setup to set up

This commit is contained in:
Michael Currin
2021-06-08 18:00:21 +02:00
parent 16e004a200
commit 828bf66208
7 changed files with 15 additions and 19 deletions

View File

@@ -9,14 +9,14 @@
[![Made with MkDocs](https://img.shields.io/badge/MkDocs-~=1.1-blue)](https://www.mkdocs.org/)
[![CI - GH Actions](https://img.shields.io/badge/CI-GH_Actions-blue?logo=github-actions&logoColor=white)](https://github.com/features/actions)
A template, live demo and tutorial for how to setup a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.
A template, live demo and tutorial for how to set up a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.
<!-- TODO When creating a new project copied from this template, you can delete this README.md and start over -->
## Purpose
This project provides low-code content-focused way to setup and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.
This project provides low-code content-focused way to set up and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.
A GitHub Actions workflow is provided with this template so you can easily deploy to GitHub Pages too.
@@ -81,7 +81,7 @@ If you're new to MkDocs, look at the tutorial added on this project's site, othe
This project provides a way to write your docs in markdown and build a professional-looking docs site on top of it, without having to write HTML or CSS code and using a selection of themes. While MkDocs CLI has functionality to deploy from a local command-line, this project makes deploying effortless by using GitHub Actions to build and deploy the site to a `gh-pages` branch and GitHub Pages to serve the site.
Compared with Jekyll and Docsify, I found the MkDocs code is much lighter to setup and changing themes is much easier than Jekyll. Also you get the benefits SEO which Docsify doesn't have. And it includes a search bar using JS.
Compared with Jekyll and Docsify, I found the MkDocs code is much lighter to set up and changing themes is much easier than Jekyll. Also you get the benefits SEO which Docsify doesn't have. And it includes a search bar using JS.
## Contributing

View File

@@ -38,4 +38,4 @@ If you are new to markdown, see the [Getting Started](https://www.markdownguide.
## 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.
MkDocs is built in Python (like Sphinx), but you don't have to write Python code. If you set up a [Deploy](deploy) flow right, you don't even have to set it up locally, though then you can't preview.

View File

@@ -1,7 +1,7 @@
# 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).
Once you've got the [Set up Project](setup-project.md) section, you can customize further using this guide. Or skip this and go to [Usage](usage.md).
## Navbar nesting
@@ -27,7 +27,7 @@ See [Configuration](https://www.mkdocs.org/user-guide/configuration/) page on Mk
## 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.
You can also structure your project to have the set up 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/`

View File

@@ -51,7 +51,7 @@ $ mkdocs gh-deploy --help
```
### Deploy with GitHub Actions
> Setup continuous deployment config to enable deploys on a change to files on GitHub
> Set up 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.

View File

@@ -12,9 +12,9 @@
<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
## Setup a new repo
## Set up a new repo
Follow the Tutorial page to setup a project from scratch.
Follow the Tutorial page to set up a project from scratch.
Or click this create your own copy of the repo.
@@ -69,4 +69,3 @@ python3 -m pip install mkdocs
```
If you get prompted for `sudo` use, then cancel and run again with `-U` flag for user-level install.

View File

@@ -1,4 +1,4 @@
# Setup project
# Set up project
> How to create a MkDocs site from scratch
This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
@@ -9,8 +9,7 @@ This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
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.
- Follow the extended guide to create a [Set up up docs site](#setup-a-docs-site) by hand.
### Basic structure
@@ -29,14 +28,12 @@ Notes on fields for the config:
- `repo_url` - for _Edit on GitHub_ button. See [docs](https://www.mkdocs.org/user-guide/configuration/#repo_url).
- `edit_uri` - defaults to `edit/master/docs/`, which includes `docs` directory of markdown files inside your repo root. But, if the site's root is in an outer `docs` directory, then you need to _also_ add that, so paths do not break. e.g. `edit/master/docs/docs`. See [docs](https://www.mkdocs.org/user-guide/configuration/#edit_uri)
### 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.
@@ -48,9 +45,9 @@ 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
### Set up a docs site
_Tip: Optionally use the `new` command covered above to setup the config and index page first and then continue_.
_Tip: Optionally use the `new` command covered above to set up the config and index page first and then continue_.
1. Create doc pages.
1. Create a `docs` directory.
@@ -138,7 +135,7 @@ theme:
### Material for MkdDocs theme
See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Setup page for config options.
See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Set up page for config options.
`requirements.txt`:
```

View File

@@ -6,7 +6,7 @@
1. [Install](installation.md)
- `pip install mkdocs`
2. [Setup project](setup-project.md)
2. [Set up project](setup-project.md)
- `mkdocs new .` or [![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f&logo=github)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
3. [Run](usage.md)
- `mkdocs serve`