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

docs: Rename Github to GitHub

Browse Source
This commit is contained in:
Michael Currin
2020-10-17 15:01:58 +02:00
parent 787dc334a1
commit b842ce958e
5 changed files with 20 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@@ -26,8 +26,8 @@ This project uses the Read the Docs theme as seen above. It comes with MkDocs so
## How to use this project
<div align="center">
[![GH Pages](https://img.shields.io/badge/Github_Pages-MkDocs_Quickstart-green?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)
[![GH Pages](https://img.shields.io/badge/GitHub_Pages-MkDocs_Quickstart-green?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)
[![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge&logo=github)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
</div>
@@ -59,14 +59,14 @@ This repo also doubles as a template to create a new project from. Click the but
Change the content and theme to suit your needs, based on the tutorial site or the MkDocs site.
## Why use MkDocs?
## Why use MkDocs?
If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs documentation.
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.
## Contributing
@@ -76,7 +76,7 @@ Or submit a code change:
1. Fork this project.
2. Set up the project locally - follow the instructions on the live tutorial or in the [TLDR](/docs/tutorial/tldr.md) page of the local docs.
3. Make any changes you want. Be sure to keep a copy of the original license in the repo.
3. Make any changes you want. Be sure to keep a copy of the original license in the repo.
- e.g. `cp LICENSE LICENSE-source`
4. Create a Pull Request.

2
docs/about-mkdocs.md
View File

@@ -22,7 +22,7 @@ If you are new to markdown, see the [Getting Started](https://www.markdownguide.
## Reasons to use MkDocs
- Create an elegant, modern docs site for your project.
- Create a static site and serve from Github Pages easily.
- 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.

4
docs/index.md
View File

@@ -1,5 +1,5 @@
# MkDocs Quickstart
> A template, live demo and tutorial for how to setup a MkDocs docs site on Github Pages
> 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)
@@ -19,7 +19,7 @@ Follow the tutorial to add an existing project or create a project from scratch.
- **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.
- 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.

18
docs/tutorial/deploy.md
View File

@@ -5,13 +5,13 @@
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.
## 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.
- [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 and not Organization or User Pages._
@@ -19,7 +19,7 @@ _Note this is for a Project Page and not Organization or User Pages._
### 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.
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:
@@ -31,9 +31,9 @@ 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
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_.
Then go to your repo on GitHub, see the *environment* tab and click _View deployment_.
e.g.
@@ -46,10 +46,10 @@ See deploy options:
mkdocs gh-deploy --help
```
### Deploy with Github Actions
> Setup continous deployment config to enable deploys on a change to files on Github
### Deploy with GitHub Actions
> Setup continous 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.
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:

6
docs/tutorial/tldr.md
View File

@@ -17,12 +17,12 @@
### Run deploy command locally
1. [Deploy](deploy.md) to Github Pages
1. [Deploy](deploy.md) to GitHub Pages
- `mkdocs gh-deploy`
2. View published site on Github Pages at `https://USERNAME.github.io/REPO-NAME/`
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.
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.