{"id":16614159,"url":"https://github.com/ctxz/mkauthdocs","last_synced_at":"2025-03-21T14:31:16.603Z","repository":{"id":57442072,"uuid":"122844065","full_name":"CTXz/mkauthdocs","owner":"CTXz","description":"A tool made to implement simple authentication on top of mkdocs builds.","archived":false,"fork":false,"pushed_at":"2023-06-17T03:31:45.000Z","size":79,"stargazers_count":18,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T02:11:16.537Z","etag":null,"topics":["auth","authentication","credentials","login","mkdocs","security"],"latest_commit_sha":null,"homepage":"","language":"Python","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/CTXz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2018-02-25T14:37:16.000Z","updated_at":"2024-07-18T19:59:00.000Z","dependencies_parsed_at":"2024-10-28T10:50:04.199Z","dependency_job_id":null,"html_url":"https://github.com/CTXz/mkauthdocs","commit_stats":{"total_commits":17,"total_committers":2,"mean_commits":8.5,"dds":"0.17647058823529416","last_synced_commit":"0e04c5512488cb87fd2082f5e76a268ec4a88042"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTXz%2Fmkauthdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTXz%2Fmkauthdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTXz%2Fmkauthdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTXz%2Fmkauthdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CTXz","download_url":"https://codeload.github.com/CTXz/mkauthdocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244815156,"owners_count":20514904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["auth","authentication","credentials","login","mkdocs","security"],"created_at":"2024-10-12T02:04:52.199Z","updated_at":"2025-03-21T14:31:16.597Z","avatar_url":"https://github.com/CTXz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mkauthdocs \u003c!-- omit in toc --\u003e\nMkauthdocs is a tool specifically made to implement simple authentication around [mkdocs](www.mkdocs.org) builds.\n\n![Screenshot](img/Screenshot.png)\n\n## Table of contents \u003c!-- omit in toc --\u003e\n- [Installation](#installation)\n- [Usage](#usage)\n- [Functional overview](#functional-overview)\n- [License](#license)\n\n## Installation\n\nMkauthdocs can be directly installed from the [Python Package Index](https://pypi.python.org/pypi/pip)\n```sh\npip install mkauthdocs\n```\n\n## Usage\n```\nusage: mkauthdocs.py [-h] [--heading HEADING] username password build_dir\n\npositional arguments:\n  username           Username used for authentication\n  password           Password used for authentication\n  build_dir          Path to build output directory\n\noptional arguments:\n  -h, --help         show this help message and exit\n  --heading HEADING  Heading on login page (default: 'Login')\n```\n\n\u003e **Warning: The password is stored as plain text in the generated php code! Altough this code is only accessible to the server, it is still a risk you should be aware of!**\n\n\u003e Note: This tool **only** applies on **mkdocs builds**, not previews served by `mkdocs serve`\n\nThis section attempts to guide the reader trough a typical use case in oder to provide understanding in a context-based environment.\n\nWe begin by building our documentation using mkdocs:\n```\nmkdocs build\n```\n\nBy default, this will output the generated documentation to the `site/` directory, which will be passed to the tool as an argument (see `build_dir` in [Usage](#usage)).\n\nNow we proceed to add authentication support to the documentation using `mkauthdocs`. The login credentials will be configured the following way:\n\n|Username|`administrator`|\n|--------|--------|\n|**Password**|`admin`|\n\n*If that isn't the safest password ever ;)*\n\nIn addition, we will set the heading of our login page to `Example Reference`. Together, that makes up for the following command:\n\n```bash\nmkauthdocs administrator admin site/ --heading \"Example Reference\"\n```\n\nIf no feedback has been returned, the documentation should be protected and ready for deployment!\n\n![Screenshot of Result](img/Screenshot2.png)\n\n## Functional overview\n\nAs `.htaccess` and `.htpasswd` configurations aren't always a possibility when hosting websites on a proprietary webspace, I was in need of a tool that would allow me to protect the publicly accessible mkdocs build. After endless searching I have only stumbled upon undocumented, incomplete and dated software which ultimately forced me to write my very own minimal tool, providing basic credential authentication to my publicly hosted mkdocs build.\n\nMkauthdocs implements authentication by injecting a minimally customizable login form into the mkdocs build directory (typically `site/`) and appending PHP session guards at the top of every page.\n\nThe login page as well as the session guards are generated from templates which can be found in the [mkauthdocs/templates/](mkauthdocs/templates) directory. If necessary, with a bit of php and html skills those can be customized as desired.\n\n**Example of a generated PHP guard for the index page:**\n```php\n\u003c?php\n  session_start();\n  if (! isset($_SESSION['login']) || ! $_SESSION['login']) {\n    $dirname = $_SERVER['REQUEST_URI'] ?? '';\n    $dirname = preg_replace('/index.php$/', '', $dirname);\n\n    header(\"Location: \".$dirname.\"{calibration}login.php?redirect={redirect}\");\n  }\n?\u003e\n\n```\n\nAccess to the site is restricted based on the state of the `login` session variable (`$_SESSION['login']`). The user is only granted access if the variable is set to `true`. If the `login` variable is not set or is `false`, the user is redirected to the login page.\n\nTo gain access, the user must authenticate themselves on the login page. Upon successful authentication, the `$_SESSION['login']` variable is set to `true`, allowing the user to proceed to the documentation.\n\nIf the provided credentials match those set in the generated login page, the user is redirected to the page they originally attempted to access. The destination page after successful login is determined by the `redirect` URL parameter, which is set by the session guards. This mechanism ensures a smooth transition to the desired page following successful authentication.\n\n## License\nAll files provided by this project fall under the OSS [MIT License](https://en.wikipedia.org/wiki/MIT_License)\n```\nThe MIT License (MIT)\n\nCopyright (c) 2018 Patrick Pedersen\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctxz%2Fmkauthdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctxz%2Fmkauthdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctxz%2Fmkauthdocs/lists"}