{"id":19293517,"url":"https://github.com/reloaded-project/devops-mkdocs","last_synced_at":"2026-03-02T13:31:31.456Z","repository":{"id":244598680,"uuid":"815708242","full_name":"Reloaded-Project/devops-mkdocs","owner":"Reloaded-Project","description":"GitHub Actions Composite Action for Building and (Optionally) Publishing a MkDocs Material Website","archived":false,"fork":false,"pushed_at":"2025-12-04T06:04:32.000Z","size":218,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"v1-master","last_synced_at":"2025-12-06T12:33:47.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Reloaded-Project.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-15T22:49:11.000Z","updated_at":"2025-12-04T06:02:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"4c07970c-2f1c-496a-9cfa-01285a8bba1b","html_url":"https://github.com/Reloaded-Project/devops-mkdocs","commit_stats":null,"previous_names":["reloaded-project/devops-mkdocs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Reloaded-Project/devops-mkdocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-mkdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-mkdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-mkdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-mkdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Reloaded-Project","download_url":"https://codeload.github.com/Reloaded-Project/devops-mkdocs/tar.gz/refs/heads/v1-master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-mkdocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30004510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T12:19:43.414Z","status":"ssl_error","status_checked_at":"2026-03-02T12:19:02.215Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T22:35:17.522Z","updated_at":"2026-03-02T13:31:31.448Z","avatar_url":"https://github.com/Reloaded-Project.png","language":null,"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Reloaded-Project/reloaded-templates-rust\" target=\"_blank\"\u003e\n    \u003cimg src=\"assets/reloaded-logo.png\" alt=\"reloaded Logo\" width=\"100\"/\u003e\n  \u003c/a\u003e\n\n  \u003ch1 align=\"center\"\u003eReloaded MkDocs Workflow\u003c/h1\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nThis is a simple action that can be used to create an MkDocs page and upload it to GitHub Pages.\n\n## Example Usage\n\n`.github/workflows/mkdocs.yml`:\n\n```yaml\nname: MkDocs Build and Deploy\n\non:\n  workflow_dispatch:\n  push:\n    branches: [ main ]\n    paths:\n      - \"mkdocs.yml\"\n      - \"docs/**\"\n  pull_request:\n    branches: [ main ]\n    paths:\n      - \"mkdocs.yml\"\n      - \"docs/**\"\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pages: write\n      id-token: write\n    steps:\n      - name: Deploy MkDocs\n        uses: Reloaded-Project/devops-mkdocs@v1\n        with:\n          requirements: ./docs/requirements.txt\n          publish-to-pages: ${{ github.event_name == 'push' }}\n          checkout-current-repo: true\n```\n\n## Setup\n\nTo use this action in your own repository:\n\n1. Create a new workflow file (e.g., `.github/workflows/mkdocs.yml`) in your repository.\n2. Copy the example usage code from above into the new workflow file.\n3. If you have additional Python dependencies, create a `requirements.txt` file in your `docs` \n   directory and list them there.\n\nEnsure your MkDocs configuration file is named `mkdocs.yml` and located in the root of your\nrepository (or update the `config-file` parameter in the workflow).\n\n## Configuration\n\n### Inputs\n\n| Input                     | Required | Default                   | Description                                    |\n| ------------------------- | -------- | ------------------------- | ---------------------------------------------- |\n| `mkdocs-version`          | No       | `latest`                  | MkDocs version to use                          |\n| `requirements`            | No       | `./docs/requirements.txt` | Path to the requirements.txt file              |\n| `config-file`             | No       | `mkdocs.yml`              | Path to the mkdocs.yml file                    |\n| `publish-to-pages`        | No       | `true`                    | Whether to publish to GitHub Pages             |\n| `checkout-current-repo`   | No       | `true`                    | Whether to perform repository checkout         |\n| `output-directory`        | No       | `./site`                  | Custom output directory for the MkDocs build   |\n| `pre-build-command`       | No       |                           | Path to the pre-build command                  |\n| `pre-build-command-shell` | No       | `bash`                    | Shell to use for running the pre-build command |\n\n### Workflow Triggers\n\nBy default, the example workflow runs on:\n\n- Pushes to the `main` branch that modify the `mkdocs.yml` file or files in the `docs/` directory.\n- Pull requests targeting the `main` branch that modify the `mkdocs.yml` file or files in the \n  `docs/` directory.\n- Manual runs triggered via the `workflow_dispatch` event.\n\nModify the `on` section of the workflow as needed for your desired trigger conditions.\n\n## Examples\n\nFind more examples in [the tests](./.github/workflows/test-mkdocs-workflow.yml).\n\n### Custom MkDocs Version\n\n```yaml\n- name: Deploy MkDocs\n  uses: Reloaded-Project/devops-mkdocs@v1\n  with:\n    mkdocs-version: '9.5.24'\n```\n\n### Custom Pre-build Command (Bash)\n\n```yaml\n- name: Deploy MkDocs\n  uses: Reloaded-Project/devops-mkdocs@v1\n  with:\n    pre-build-command: touch pre-build-bash-executed.txt\n    pre-build-command-shell: bash\n```\n\n### Custom Output Directory\n\n```yaml\n- name: Deploy MkDocs\n  uses: Reloaded-Project/devops-mkdocs@v1\n  with:\n    output-directory: custom_site_dir\n```\n\n### Locked Requirements for Reproducible Builds\n\nTo guarantee your documentation builds consistently over time and avoid plugin version incompatibilities, \nlock your dependencies using `pip-tools`.\n\nAssuming you have a local Python installation:\n\nCreate a `docs/requirements.in` with MkDocs Material and your plugins:\n\n```txt\nmkdocs-material==9.5.24\nmkdocs-git-revision-date-localized-plugin\nmkdocs-awesome-pages-plugin\nmkdocs-minify-plugin\n```\n\nGenerate locked `docs/requirements.txt`:\n\n```bash\npip install pip-tools\npip-compile docs/requirements.in -o docs/requirements.txt\n```\n\nUse in workflow:\n\n```yaml\n- name: Deploy MkDocs\n  uses: Reloaded-Project/devops-mkdocs@v1\n  with:\n    requirements: ./docs/requirements.txt\n```\n\n**Note:** If `mkdocs-material` is present in your `requirements.txt`, the action will install only \nfrom the requirements file (ignoring the `mkdocs-version` input). If `mkdocs-material` is not in \nyour requirements, the action will install it from the `mkdocs-version` input alongside your \nrequirements, letting pip resolve compatible versions.\n\nTo update dependencies, edit `docs/requirements.in` and regenerate:\n\n```bash\npip-compile --upgrade docs/requirements.in -o docs/requirements.txt\n```\n\n#### Testing Locally\n\nTest locked requirements in a clean environment:\n\n```bash\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Windows: .venv\\Scripts\\activate\n\n# Install pip-tools and generate locked requirements\npip install pip-tools\npip-compile docs/requirements.in -o docs/requirements.txt\n\n# Install and test\npip install -r docs/requirements.txt\nmkdocs build\n\n# Deactivate when done\ndeactivate\n```\n\n## Viewing the Generated Docs\n\nAfter a successful run, the generated static site will be available on the GitHub Pages site for\nyour repository.\n\nTo find the URL:\n\n1. Navigate to your repository on GitHub.\n2. Go to the \"Settings\" tab.\n3. Click on \"Pages\" in the side navigation.\n4. The GitHub Pages URL will be listed at the top, in the format \n   `https://\u003cuser\u003e.github.io/\u003crepo\u003e/`.\n\n## Why this Exists?\n\nPrevious actions for MkDocs that I've used relied on virtualization, such as Docker. This was slow\nand sometimes inflexible, for example, the Docker image may not have the latest version of MkDocs\nif not configured properly.\n\nThis action directly invokes `pip` and `python` on the host machine for improved performance and\nflexibility.\n\n## Contributing\n\nContributions are welcome! If you encounter any issues or have suggestions for improvements,\nplease open an issue or submit a pull request in this repository.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freloaded-project%2Fdevops-mkdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freloaded-project%2Fdevops-mkdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freloaded-project%2Fdevops-mkdocs/lists"}