Skip to content

Commit 82bb32d

Browse files
ocaisaocaisa
authored
Initial commit
0 parents  commit 82bb32d

File tree

11 files changed

+830
-0
lines changed

11 files changed

+830
-0
lines changed

‎.github/dependabot.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Feel free to alter this file to your liking when using the template.
2+
# It allows to keep dependencies up to date using Dependabot.
3+
#
4+
# If you use Dependabot-Preview can you easly switch to Dependabot, by logging into the dashboard at
5+
# https://dependabot.com and click the "Create config file" button of your repository.
6+
# The bot should make a Pull request with the config file that you then can modify if you want.
7+
#
8+
# You can find more info about the file-format here:
9+
# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
10+
11+
version: 2
12+
updates:
13+
- package-ecosystem: "pip" # See documentation for possible values
14+
directory: "/" # Location of package manifests
15+
schedule:
16+
interval: "daily"
17+
labels:
18+
- 'Type: Update (Dependency)'
19+
- 'Target: Python (pip)'
20+
- package-ecosystem: "github-actions"
21+
directory: "/" # Location of package manifests
22+
schedule:
23+
interval: "daily"
24+
labels:
25+
- 'Type: Update (Dependency)'
26+
- 'Target: GitHub Actions'

‎.github/workflows/deploy.yml

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
#
2+
# This is a working example of using GitHub Actions to publish the docs
3+
# to the GitHub Pages (gh_pages) branch.
4+
#
5+
# Remember to have a requirements.txt file with the required dependencies.
6+
# This template ships with one by default.
7+
#
8+
# It is also recommendet to also copy the template with all branches, to
9+
# have the gh-pages branch pre-made. This prevents possible errors.
10+
#
11+
name: Deploy Site
12+
13+
on:
14+
push:
15+
paths:
16+
- 'docs/**'
17+
- 'mkdocs.yml'
18+
- 'theme/**'
19+
branches:
20+
- master
21+
#
22+
# If your repository would have releases should you uncomment the below lines
23+
# in order to ignore pushes caused by newly created releases.
24+
#
25+
#tags-ignore:
26+
#- '**'
27+
28+
jobs:
29+
build:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- uses: actions/checkout@v3
33+
- name: Set up Python 3.7
34+
uses: actions/setup-python@v4
35+
with:
36+
python-version: 3.7
37+
- name: Install dependencies
38+
run: |
39+
python -m pip install --upgrade pip setuptools
40+
python -m pip install -r requirements.txt
41+
- name: Deploy Files
42+
run: |
43+
git config user.name "github-actions[bot]"
44+
git config user.email "[email protected]"
45+
mkdocs gh-deploy --force

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2020 Andre601
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
[use]: https://github.com/Andre601/mkdocs-template/generate
2+
3+
[MkDocs]: https://www.mkdocs.org/
4+
5+
[squidfunk]: https://github.com/squidfunk
6+
[MkDocs Material Theme]: https://github.com/squidfunk/mkdocs-material
7+
8+
[facelessuser]: https://github.com/facelessuser
9+
[PyMdown Extensions]: https://github.com/facelessuser/pymdown-extensions/
10+
11+
[Netlify]: https://netlify.com
12+
13+
[mkdocs.yml]: https://github.com/Andre601/mkdocs-template/blob/master/mkdocs.yml
14+
[docs folder]: https://github.com/Andre601/mkdocs-template/blob/master/docs
15+
[workflow]: https://github.com/Andre601/mkdocs-template/blob/master/.github/workflows/deploy.yml
16+
17+
[LICENSE]: https://github.com/Andre601/mkdocs-template/blob/master/LICENSE
18+
19+
[gh-pages]: https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
20+
21+
# MkDocs Material Template
22+
This is a template repository for anyone that wants to use the MkDocs Material Theme.
23+
24+
## Getting Started
25+
To get started, first clone this template by clicking on the Green button labeled [`Use this template`][use].
26+
On the new screen, give your repository a name and make sure to check `Include all branches`. This will make sure that the `gh-pages` branch is included, or otherwhise publishing the docs to GitHub Pages could cause errors (See [Troubleshooting](#troubleshooting)).
27+
28+
> **Note**
29+
> GitHub changed how you define from where it takes the pages to build. You are now able to define both a branch and a specific folder from where GitHub would take the files to then deploy them on GitHub Pages.
30+
> You can read more about this [here][gh-pages].
31+
32+
### Creating pages
33+
To create new pages, just add new markdown files to the [docs folder] of the repository and edit them.
34+
MkDocs will then turn those into static HTML pages once you [build](#build-pages) or [deploy](#deploy-to-github) the pages.
35+
36+
The template also has some pre-made settings for your convenience to help you with creating documentation much easier.
37+
In the [mkdocs.yml] will you find many settings that you can alter. Please check the comments and the links they have for more info.
38+
39+
It also contains some extensions that might be useful including:
40+
41+
- Admonition
42+
- CodeHilite
43+
- ToC
44+
- [PyMdown Extensions]
45+
46+
You're free to add, edit or remove any extension at your own discretion, but keep in mind that some expansions might cause compatibility issues with others or require to be downloaded first.
47+
For that, alter the `requirements.txt` if you also deploy pages using GitHub Actions or [Netlify](#netlify)
48+
49+
## Build Pages
50+
To build pages (locally) can you use the `mkdocs build` command in your prefered command prompt.
51+
Note that for the successful execution of this command you have to...
52+
53+
- ...be in the folder that contains the `mkdocs.yml`
54+
- ...have Python 3.7 installed
55+
- ...have MkDocs and all required dependencies such as Material for MkDocs installed.
56+
Note that Material for MkDocs automatically downloads MkDocs and also certain extensions such as the [PyMdown Extensions].
57+
58+
MkDocs would now build the HTML in the defined configuration folder for you to use.
59+
60+
## Deploy to GitHub
61+
If you want to publish the pages on GitHub Pages can you use the [premade workflow][workflow] for this.
62+
This workflow will setup Python, download Material for MkDocs and all its dependencies and deploy the pages to the `gh-pages` branch to then be viewable under `<username>.github.io/<repository>` (unless you defined a specific CNAME through a CNAME file in the [docs folder]).
63+
64+
Note that in order for this to work will you need to have a `gh-pages` branch already made.
65+
66+
## Netlify
67+
Netlify is an amazing service to build and deploy pages. This template comes with a `runtime.txt` which is used by Netlify to determine the Python version used (They use an old version of Python... Don't ask why).
68+
69+
For more information, please check out their website.
70+
71+
## Dependabot
72+
The repository contains a `dependabot.yml` file inside the `.github` folder which allows automatic updates through GitHub's Dependabot.
73+
It is configured to target both Python dependencies (inside the `requirements.txt`) and GitHub Actions dependencies, to make sure bot are updated accordingly.
74+
75+
Note that it is configured by default to add the `Type: Update (Dependency)` label and also the `Target: Python (pip)` label for Python and `Target: GitHub Actions` label for GitHub Actions Dependencies.
76+
Those labels don't exist by default so you have to either create them, or alter the ones in the dependabot.yml (You can also just remove the `labels` sections).
77+
78+
## Troubleshooting
79+
> **The deploy action gives me an error when deploying. What is the issue?**
80+
81+
There can be many issues but the most common ones are that you either don't have a `gh-pages` branch set or that the `requirements.txt` file is missing or its content is invalid.
82+
83+
> **Can I alter the overall style of the pages?**
84+
85+
Yes. Material for MkDocs supports Theme extensions, meaning you can override specific parts of a theme by providing the particular file in a folder and defining this folder as the `custom_dir` one in the [mkdocs.yml].
86+
This template ships with a `theme` folder that can be used for that and you can just uncomment the aforementioned line in the YAML file.
87+
88+
89+
## Credits
90+
A big thank you goes to the following people/groups:
91+
92+
- [MkDocs] for providing the software, to generate documentation.
93+
- [squidfunk] for the [MkDocs Material Theme].
94+
- [facelessuser] for the [PyMdown Extensions].
95+
96+
## License
97+
This template is served under the MIT license.
98+
Read the [LICENSE] file for more info.

‎docs/assets/css/extensions/tabbed.css

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
.tabbed-set {
2+
display: flex;
3+
position: relative;
4+
flex-wrap: wrap;
5+
}
6+
7+
.tabbed-set .highlight {
8+
background: #ddd;
9+
}
10+
11+
.tabbed-set .tabbed-content {
12+
display: none;
13+
order: 99;
14+
width: 100%;
15+
}
16+
17+
.tabbed-set label {
18+
width: auto;
19+
margin: 0 0.5em;
20+
padding: 0.25em;
21+
font-size: 120%;
22+
cursor: pointer;
23+
color: #ffffff !important;
24+
}
25+
26+
.tabbed-set input {
27+
position: absolute;
28+
opacity: 0;
29+
}
30+
31+
.tabbed-set input:nth-child(n+1) {
32+
color: #333333;
33+
}
34+
35+
.tabbed-set input:nth-child(n+1):checked + label {
36+
color: cyan !important;
37+
}
38+
39+
.tabbed-set input:nth-child(n+1):checked + label + .tabbed-content {
40+
display: block;
41+
}

‎docs/assets/css/extra.css

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@import "extensions/tabbed.css";

‎docs/index.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
[use]: https://github.com/Andre601/mkdocs-template/generate
2+
3+
[MkDocs]: https://www.mkdocs.org/
4+
5+
[squidfunk]: https://github.com/squidfunk
6+
[MkDocs Material Theme]: https://github.com/squidfunk/mkdocs-material
7+
8+
[facelessuser]: https://github.com/facelessuser
9+
[PyMdown Extensions]: https://github.com/facelessuser/pymdown-extensions/
10+
11+
[Netlify]: https://netlify.com
12+
13+
[mkdocs.yml]: https://github.com/Andre601/mkdocs-template/blob/master/mkdocs.yml
14+
[docs folder]: https://github.com/Andre601/mkdocs-template/blob/master/docs
15+
[workflow]: https://github.com/Andre601/mkdocs-template/blob/master/.github/workflows/deploy.yml
16+
17+
[LICENSE]: https://github.com/Andre601/mkdocs-template/blob/master/LICENSE
18+
19+
# MkDocs Material Template
20+
This is a template repository for anyone that wants to use the MkDocs Material Theme.
21+
22+
## Getting Started
23+
To get started, first clone this template by clicking on the Green button labeled [`Use this template`][use].
24+
On the new screen, give your repository a name and make sure to check `Include all branches`. This will make sure that the `gh-pages` branch is included, or otherwhise publishing the docs to GitHub Pages could cause errors (See [Troubleshooting](#troubleshooting)).
25+
26+
### Creating pages
27+
To create new pages, just add new markdown files to the [docs folder] of the repository and edit them.
28+
MkDocs will then turn those into static HTML pages once you [build](#build-pages) or [deploy](#deploy-to-github) the pages.
29+
30+
The template also has some pre-made settings for you to help you with creating documentation much easier.
31+
In the [mkdocs.yml] will you find many settings that you can alter. Please check the comments and the links they have for more info.
32+
33+
It also contains some extensions that might be useful including:
34+
35+
- Admonition
36+
- CodeHilite
37+
- ToC
38+
- [PyMdown Extensions]
39+
40+
You're free to add, edit or remove any extension at your own discretion, but keep in mind that some expansions might caus compatibility issues with others.
41+
42+
## Build Pages
43+
To build pages (locally) can you use the `mkdocs build` command in your prefered command prompt.
44+
Note that for the successful execution of this command you have to...
45+
46+
- ...be in the folder that contains the `mkdocs.yml`
47+
- ...have Python 3.7 installed
48+
- ...have MkDocs and all required dependencies such as Material for MkDocs installed.
49+
Note that Material for MkDocs automatically downloads MkDocs and also certain extensions such as the [PyMdown Extensions].
50+
51+
MkDocs would now build the HTML in the defined configuration folder for you to use.
52+
53+
## Deploy to GitHub
54+
If you want to publish the pages on GitHub Pages can you use the [premade workflow][workflow] for this.
55+
This workflow will setup Python, download Material for MkDocs and all its dependencies and deploy the pages to the `gh-pages` branch to then be viewable under `<username>.github.io/<repository>` (unless you defined a specific CNAME through a CNAME file in the [docs folder]).
56+
57+
Note that in order for this to work will you need to have a `gh-pages` branch already made.
58+
59+
## Netlify
60+
Netlify is an amazing service to build and deploy pages. This template comes with a `runtime.txt` which is used by Netlify to determine the Python version used (They use an old version of Python... Don't ask why).
61+
62+
For more information, please check out their website.
63+
64+
## Troubleshooting
65+
> **The deploy action gives me an error when deploying. What is the issue?**
66+
67+
There can be many issues but the most common ones are that you either don't have a `gh-pages` branch set or that the `requirements.txt` file is missing or its content is invalid.
68+
69+
> **Can I alter the overall style of the pages?**
70+
71+
Yes. Material for MkDocs supports Theme extensions, meaning you can override specific parts of a theme by providing the particula file in a folder and defining this folder as the `custom_dir` one in the [mkdocs.yml].
72+
This template ships with a `theme` folder that can be used for that and you can just uncomment the aforementioned line in the YAML file.
73+
74+
## Dependabot
75+
The repository contains a `dependabot.yml` file inside the `.github` folder which allows automatic updates through GitHub's Dependabot.
76+
It is configured to target both Python dependencies (inside the `requirements.txt`) and GitHub Actions dependencies, to make sure bot are updated accordingly.
77+
78+
Note that it is configured by default to add the `Type: Update (Dependency)` label and also the `Target: Python (pip)` label for Python and `Target: GitHub Actions` label for GitHub Actions Dependencies.
79+
Those labels don't exist by default so you have to either create them, or alter the ones in the dependabot.yml (You can also just remove the `labels` sections).
80+
81+
## Credits
82+
A big thank you goes to the following people/groups:
83+
84+
- [MkDocs] for providing the software, to generate documentation.
85+
- [squidfunk] for the [MkDocs Material Theme].
86+
- [facelessuser] for the [PyMdown Extensions].
87+
88+
## License
89+
This template is served under the MIT license.
90+
Read the [LICENSE] file for more info.

0 commit comments

Comments
 (0)