Skip to content

Commit c366b12

Browse files
Sewer56Sewer56
committed
Merge branch 'init'
2 parents 9de8ec4 + 9e10c3f commit c366b12

6 files changed

Lines changed: 412 additions & 1 deletion

File tree

‎.github/workflows/test-mkdocs-workflow.yml‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
name: Test MkDocs Workflow
2+
3+
on:
4+
schedule:
5+
- cron: '0 0 * * 0' # Run every Sunday at midnight
6+
workflow_dispatch:
7+
push:
8+
branches: [ master ]
9+
paths:
10+
- 'action.yml'
11+
- '.github/workflows/test-mkdocs-workflow.yml'
12+
pull_request:
13+
branches: [ master ]
14+
paths:
15+
- 'action.yml'
16+
- '.github/workflows/test-mkdocs-workflow.yml'
17+
18+
jobs:
19+
test-default-parameters:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout Test Repository
23+
uses: actions/checkout@v4
24+
with:
25+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
26+
submodules: 'recursive'
27+
- name: Test Default Parameters
28+
uses: Reloaded-Project/devops-mkdocs@v1
29+
with:
30+
checkout-current-repo: false
31+
publish-to-pages: false
32+
33+
test-custom-mkdocs-version:
34+
runs-on: ubuntu-latest
35+
steps:
36+
- name: Checkout Test Repository
37+
uses: actions/checkout@v4
38+
with:
39+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
40+
submodules: 'recursive'
41+
- name: Test Custom MkDocs Version
42+
uses: Reloaded-Project/devops-mkdocs@v1
43+
with:
44+
mkdocs-version: '9.5.24'
45+
checkout-current-repo: false
46+
publish-to-pages: false
47+
48+
test-custom-pre-build-command-bash:
49+
runs-on: ubuntu-latest
50+
steps:
51+
- name: Checkout Test Repository
52+
uses: actions/checkout@v4
53+
with:
54+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
55+
submodules: 'recursive'
56+
- name: Test Custom Pre-build Command (Bash)
57+
uses: Reloaded-Project/devops-mkdocs@v1
58+
with:
59+
pre-build-command: touch pre-build-bash-executed.txt
60+
pre-build-command-shell: bash
61+
checkout-current-repo: false
62+
publish-to-pages: false
63+
- name: Assert Pre-build Command Execution (Bash)
64+
shell: bash
65+
run: |
66+
if [ ! -f pre-build-bash-executed.txt ]; then
67+
echo "Pre-build command (Bash) did not execute successfully"
68+
exit 1
69+
fi
70+
71+
test-custom-pre-build-command-pwsh:
72+
runs-on: ubuntu-latest
73+
steps:
74+
- name: Checkout Test Repository
75+
uses: actions/checkout@v4
76+
with:
77+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
78+
submodules: 'recursive'
79+
- name: Test Custom Pre-build Command (PowerShell)
80+
uses: Reloaded-Project/devops-mkdocs@v1
81+
with:
82+
pre-build-command: New-Item -ItemType File -Path pre-build-pwsh-executed.txt
83+
pre-build-command-shell: pwsh
84+
checkout-current-repo: false
85+
publish-to-pages: false
86+
- name: Assert Pre-build Command Execution (PowerShell)
87+
shell: pwsh
88+
run: |
89+
if (-not (Test-Path -Path pre-build-pwsh-executed.txt)) {
90+
Write-Error "Pre-build command (PowerShell) did not execute successfully"
91+
exit 1
92+
}
93+
94+
test-custom-output-directory:
95+
runs-on: ubuntu-latest
96+
steps:
97+
- name: Checkout Test Repository
98+
uses: actions/checkout@v4
99+
with:
100+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
101+
submodules: 'recursive'
102+
- name: Test Custom Output Directory
103+
uses: Reloaded-Project/devops-mkdocs@v1
104+
with:
105+
output-directory: custom_site_dir
106+
checkout-current-repo: false
107+
publish-to-pages: false
108+
- name: Assert Custom Output Directory
109+
shell: bash
110+
run: |
111+
if [ ! -d custom_site_dir ] || [ -z "$(ls -A custom_site_dir)" ]; then
112+
echo "Custom output directory does not exist or is empty"
113+
exit 1
114+
fi
115+
116+
test-custom-requirements-path:
117+
runs-on: ubuntu-latest
118+
steps:
119+
- name: Checkout Test Repository
120+
uses: actions/checkout@v4
121+
with:
122+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
123+
submodules: 'recursive'
124+
- name: Copy Custom Requirements File
125+
shell: bash
126+
run: cp docs/requirements.txt docs/custom-requirements.txt
127+
- name: Test Custom Requirements Path
128+
uses: Reloaded-Project/devops-mkdocs@v1
129+
with:
130+
requirements: docs/custom-requirements.txt
131+
checkout-current-repo: false
132+
publish-to-pages: false
133+
134+
test-custom-config-file:
135+
runs-on: ubuntu-latest
136+
steps:
137+
- name: Checkout Test Repository
138+
uses: actions/checkout@v4
139+
with:
140+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
141+
submodules: 'recursive'
142+
- name: Copy Custom Config File
143+
shell: bash
144+
run: cp mkdocs.yml custom-mkdocs.yml
145+
- name: Test Custom Config File
146+
uses: Reloaded-Project/devops-mkdocs@v1
147+
with:
148+
config-file: custom-mkdocs.yml
149+
checkout-current-repo: false
150+
publish-to-pages: false
151+
152+
test-publish-to-pages:
153+
runs-on: ubuntu-latest
154+
permissions:
155+
contents: read
156+
pages: write
157+
id-token: write
158+
steps:
159+
- name: Checkout Test Repository
160+
uses: actions/checkout@v4
161+
with:
162+
repository: Reloaded-Project/Reloaded.MkDocsMaterial.Themes.R2
163+
submodules: 'recursive'
164+
- name: Test Publish to Pages
165+
uses: Reloaded-Project/devops-mkdocs@v1
166+
with:
167+
publish-to-pages: true
168+
checkout-current-repo: false

‎LICENSE‎

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

‎README.MD‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
<div align="center">
2+
<a href="https://github.com/Reloaded-Project/reloaded-templates-rust" target="_blank">
3+
<img src="assets/reloaded-logo.png" alt="reloaded Logo" width="100"/>
4+
</a>
5+
6+
<h1 align="center">Reloaded MkDocs Workflow</h1>
7+
8+
<p>
9+
<a href="LICENSE">
10+
<img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
11+
</a>
12+
</p>
13+
</div>
14+
15+
This is a simple action that can be used to create an MkDocs page and upload it to GitHub Pages.
16+
17+
## Example Usage
18+
19+
`.github/workflows/mkdocs.yml`:
20+
21+
```yaml
22+
name: MkDocs Build and Deploy
23+
24+
on:
25+
workflow_dispatch:
26+
push:
27+
branches: [ main ]
28+
paths:
29+
- "mkdocs.yml"
30+
- "docs/**"
31+
pull_request:
32+
branches: [ main ]
33+
paths:
34+
- "mkdocs.yml"
35+
- "docs/**"
36+
37+
jobs:
38+
build:
39+
runs-on: ubuntu-latest
40+
permissions:
41+
contents: read
42+
pages: write
43+
id-token: write
44+
steps:
45+
- name: Deploy MkDocs
46+
uses: Reloaded-Project/devops-mkdocs@v1
47+
with:
48+
requirements: ./docs/requirements.txt
49+
publish-to-pages: true
50+
checkout-current-repo: true
51+
```
52+
53+
## Setup
54+
55+
To use this action in your own repository:
56+
57+
1. Create a new workflow file (e.g., `.github/workflows/mkdocs.yml`) in your repository.
58+
2. Copy the example usage code from above into the new workflow file.
59+
3. If you have additional Python dependencies, create a `requirements.txt` file in your `docs`
60+
directory and list them there.
61+
62+
Ensure your MkDocs configuration file is named `mkdocs.yml` and located in the root of your
63+
repository (or update the `config-file` parameter in the workflow).
64+
65+
## Configuration
66+
67+
### Inputs
68+
69+
| Input | Required | Default | Description |
70+
| ------------------------- | -------- | ------------------------- | ---------------------------------------------- |
71+
| `mkdocs-version` | No | `latest` | MkDocs version to use |
72+
| `requirements` | No | `./docs/requirements.txt` | Path to the requirements.txt file |
73+
| `config-file` | No | `mkdocs.yml` | Path to the mkdocs.yml file |
74+
| `publish-to-pages` | No | `true` | Whether to publish to GitHub Pages |
75+
| `checkout-current-repo` | No | `true` | Whether to perform repository checkout |
76+
| `output-directory` | No | `./site` | Custom output directory for the MkDocs build |
77+
| `pre-build-command` | No | | Path to the pre-build command |
78+
| `pre-build-command-shell` | No | `bash` | Shell to use for running the pre-build command |
79+
80+
### Workflow Triggers
81+
82+
By default, the example workflow runs on:
83+
84+
- Pushes to the `main` branch that modify the `mkdocs.yml` file or files in the `docs/` directory.
85+
- Pull requests targeting the `main` branch that modify the `mkdocs.yml` file or files in the
86+
`docs/` directory.
87+
- Manual runs triggered via the `workflow_dispatch` event.
88+
89+
Modify the `on` section of the workflow as needed for your desired trigger conditions.
90+
91+
## Examples
92+
93+
Find more examples in [the tests](./.github/workflows/test-mkdocs-workflow.yml).
94+
95+
### Custom MkDocs Version
96+
97+
```yaml
98+
- name: Deploy MkDocs
99+
uses: Reloaded-Project/devops-mkdocs@v1
100+
with:
101+
mkdocs-version: '9.5.24'
102+
```
103+
104+
### Custom Pre-build Command (Bash)
105+
106+
```yaml
107+
- name: Deploy MkDocs
108+
uses: Reloaded-Project/devops-mkdocs@v1
109+
with:
110+
pre-build-command: touch pre-build-bash-executed.txt
111+
pre-build-command-shell: bash
112+
```
113+
114+
### Custom Output Directory
115+
116+
```yaml
117+
- name: Deploy MkDocs
118+
uses: Reloaded-Project/devops-mkdocs@v1
119+
with:
120+
output-directory: custom_site_dir
121+
```
122+
123+
## Viewing the Generated Docs
124+
125+
After a successful run, the generated static site will be available on the GitHub Pages site for
126+
your repository.
127+
128+
To find the URL:
129+
130+
1. Navigate to your repository on GitHub.
131+
2. Go to the "Settings" tab.
132+
3. Click on "Pages" in the side navigation.
133+
4. The GitHub Pages URL will be listed at the top, in the format
134+
`https://<user>.github.io/<repo>/`.
135+
136+
## Why this Exists?
137+
138+
Previous actions for MkDocs that I've used relied on virtualization, such as Docker. This was slow
139+
and sometimes inflexible, for example, the Docker image may not have the latest version of MkDocs
140+
if not configured properly.
141+
142+
This action directly invokes `pip` and `python` on the host machine for improved performance and
143+
flexibility.
144+
145+
## Contributing
146+
147+
Contributions are welcome! If you encounter any issues or have suggestions for improvements,
148+
please open an issue or submit a pull request in this repository.
149+
150+
## License
151+
152+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

‎README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)