{"id":22492510,"url":"https://github.com/six-two/mkdocs-placeholder-plugin","last_synced_at":"2025-07-05T14:39:10.531Z","repository":{"id":49320141,"uuid":"517272946","full_name":"six-two/mkdocs-placeholder-plugin","owner":"six-two","description":"Add placeholders to your MkDocs pages","archived":false,"fork":false,"pushed_at":"2025-04-29T16:40:44.000Z","size":589,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-03T01:38:50.476Z","etag":null,"topics":["mkdocs","mkdocs-plugin","plugin","search-replace"],"latest_commit_sha":null,"homepage":"https://mkdocs-placeholder-plugin.six-two.dev/","language":"TypeScript","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/six-two.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,"zenodo":null}},"created_at":"2022-07-24T08:54:44.000Z","updated_at":"2025-06-12T14:02:13.000Z","dependencies_parsed_at":"2024-04-17T17:34:45.909Z","dependency_job_id":"c25164ee-41c3-465b-af25-46ab5d34790f","html_url":"https://github.com/six-two/mkdocs-placeholder-plugin","commit_stats":{"total_commits":88,"total_committers":1,"mean_commits":88.0,"dds":0.0,"last_synced_commit":"97bef3ff5860ee4c9b35e0d5980277fd6b0d6972"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/six-two/mkdocs-placeholder-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-placeholder-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-placeholder-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-placeholder-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-placeholder-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/six-two","download_url":"https://codeload.github.com/six-two/mkdocs-placeholder-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/six-two%2Fmkdocs-placeholder-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263756751,"owners_count":23506590,"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":["mkdocs","mkdocs-plugin","plugin","search-replace"],"created_at":"2024-12-06T18:18:38.200Z","updated_at":"2025-07-05T14:39:10.525Z","avatar_url":"https://github.com/six-two.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MkDocs Placeholder Plugin\n\n[![PyPI version](https://img.shields.io/pypi/v/mkdocs-placeholder-plugin)](https://pypi.org/project/mkdocs-placeholder-plugin/)\n![License](https://img.shields.io/pypi/l/mkdocs-placeholder-plugin)\n![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-placeholder-plugin)\n\nThis plugin allows you to have placeholders in your site, that can be dynamically replaced at runtime using JavaScript (see [demo page](https://mkdocs-placeholder-plugin.six-two.dev/demo/)).\n\n\n## Documentation\n\nThis README is just a short intro to the package.\nFor a quick start and detailed information please see the [documentation for the last release](https://mkdocs-placeholder-plugin.six-two.dev/).\nThe documentation is also available in the `docs` folder of the source code and can be built locally with [MkDocs](https://www.mkdocs.org/).\n\n## Development version\n\nIf you want to use the latest development version (may be broken/buggy from time to time), you can install it by:\n\n1. Cloning the repository:\n    ```bash\n    git clone https://github.com/six-two/mkdocs-placeholder-plugin\n    cd mkdocs-placeholder-plugin\n    ```\n2. Building/Downloading the JavaScript files.\n    Choose any of the following ways:\n    \n    - Build it with npm (natively), by running the `./build-docs.sh` script.\n    - Build it in a (docker/podman) container by using the `Dockerfile` in the `typescript` directory.\n        The whole thing can be done by running the `buils.sh` script in the root directory:\n        ```bash\n        ./build.sh\n        ```\n        Once you see mkdocs running, you can terminate it with `Ctrl-C`.\n    - Downloading the files from the development version of the documentation (hosted and built by Vercel):\n        ```bash\n        curl https://dev.mkdocs-placeholder-plugin.six-two.dev/placeholder.min.js -o src/mkdocs_placeholder_plugin/assets/placeholder.min.js\n        curl https://dev.mkdocs-placeholder-plugin.six-two.dev/placeholder.min.js.map -o src/mkdocs_placeholder_plugin/assets/placeholder.min.js.map\n        ```\n3. Installing the package with pip:\n    ```bash\n    python3 -m pip install .\n    ```\n\nThe corresponding documentation is hosted at \u003chttps://dev.mkdocs-placeholder-plugin.six-two.dev\u003e.\n\n## Notable changes\n\n### Version 0.5.1\n\n- Fixes innerHTML replacement method breaking functionality such as the search box (see [#9](https://github.com/six-two/mkdocs-placeholder-plugin/issues/9)).\n\n### Version 0.5.0-1\n\n- Version 0.5.0 accidentally shipped with old JavaScript code. This causes the JavaScript to crash with the error `Type mismatch: inline_editor_icons should be boolean, but is undefined`. If you encounter this issue, make sure to update to the latest version with `pip install -U mkdocs-placeholder-plugin` or pin the fixed version with `pip install mkdocs-placeholder-plugin==0.5.0-1`.\n\n### Version 0.5.0\n\n- Added inline editable placeholders (see [#6](https://github.com/six-two/mkdocs-placeholder-plugin/issues/6)) and enabled them by default:\n    - If you want to disable them by default, add `inline_editors: false` to the `settings` attribute in your `placeholder-plugin.yaml`.\n    - If you want to disable them and prevent users from enabling them, add `normal_is_alias_for: dynamic` to the `settings` attribute in your `placeholder-plugin.yaml`.\n    - You can choose how inline placeholders look via the [`inline_editor_style` setting](https://mkdocs-placeholder-plugin.six-two.dev/configuration/#inline_editor_style).\n- You can now embed the placeholder settings editor anywhere in your page with `\u003cdiv class=\"placeholder-settings-panel\"\u003e\u003c/div\u003e`.\n\n### Version 0.4.1\n\n- Validators can copy rules from other validators via the `import_rules_from` attribute\n- New validators: `email`, `linux_interface`, `mac_address`, `uuid`\n\n### Version 0.4.0\n\n- Configuration format changed:\n    - Validators are no longer defined in-line and instead defined in a `validators` section -\u003e easier to reuse custom validators.\n    - Placeholders now need to be specified in a `placeholders` section.\n    - Most settings are now in the configuration file instead of in your `mkdocs.yml`.\n- Some actions can now be toggled by visitors of the site. The settings open when you click the gear icon on a (dynamic) placeholder input table.\n- (By default) values are saved when the focus leaves a text field.\n- Removed static placeholder input tables (`\u003cplaceholdertable\u003e`).\n- Uncoupled the code from MkDocs.\n    You should now be able to relatively easy port the project to other Markdown based static site generators if you want to.\n\n### Version 0.3.1\n\n- Removed `Apply all changes` buttons. See [issue #3](https://github.com/six-two/mkdocs-placeholder-plugin/issues/3)\n\n### Version 0.3.0\n\nThis release may be a bit buggy due to the rewrite and the documentation is not entirely accurate yet.\nI will update the docs after I also clean up / rewrite the python code (planed for v0.4.0).\n\n- Rewrote the JavaScript code in TypeScript:\n    - Packed and minified using Webpack, so the file is a bit smaller\n    - Should find stupid errors I make in code paths that I do not test (often)\n    - Sophisticated update logic: Instead of always reloading the page it tries to update the DOM in-place (if possible), which should improve user experience a bit and is much faster\n    - Nested placeholders (placeholders that contain placeholders that contain placeholder...) no longer need to be specified in a speific order in the configuration file.\n    - A placeholder's `default-function` and a validator rule's `match_function` are now evaluated using [`new Function(...)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) instead of `eval(...)`, so you need to add a return statement.\n\n### Version 0.2.5\n\n- When an JavaScript generated `auto-input-table` is empty, now a info box is shown (instead of nothing / an empty table).\n- Bugfixes:\n    - `auto_placeholder_tables_javascript` had no effect.\n    - Pressing `Enter` on text fields without validators did not try to reload the page,\n\n### Version 0.2.4\n\n- Added input validation:\n    - Predefined types: `domain`, `file_name_linux`, `file_name_windows`, `hostname`, `ipv4_address`, `ipv4_range_cidr`, `ipv4_range_dashes`, `ipv6_address`, `path_linux`, `path_windows`, `port_number`, `url_any`, `url_http`\n    - Custom validators with rules that either use `regex` or `match_function`\n- Added `placeholder_extra_js` field to plugin configuration (for loading custom functions)\n- Added `default-function` attribute for placeholders\n\n### Version 0.2.3\n\n- Split JavaScript code into multiple files and made it available via the global `PlaceholderData` and `PlaceholderPlugin` objects.\n    These interfaces are not stable, so you should probably not try to rely on them to much.\n- Added `replace_everywhere` attribute for placeholders\n- Changes to textbox values are only stored, when you press `Enter`\n- Dynamically generated tables now honor `add_apply_table_column`\n- Improved JavaScript debugging: timestamps, more messages, and you can disable the page reload\n- Some visual fixes, mainly for the `Material for MkDocs` theme\n\n### Version 0.2.2\n\n- Improved placeholder input tables:\n    - Can now specify which columns to use (and their order)\n    - Only show apply values column, if at least one column contains input elements\n- Properly handle checkboxes and dropdown menus when performing static replacements\n- Hide JavaScript console output by default\n- Generate automatic placeholder table dynamically, since if checkboxes / dropdowns are used, it can not be predicted, which values are used on the page.\n- Added `description-or-name` column type to placeholder tables.\n\n### Version 0.2.1\n\n- Add option to reload the page if a checkbox/dropdown is changed or a text field is changed and `Enter` is pressed (to immediately show the new values).\n    This is enabled by default.\n- Set initial value for placeholder input fields to \"Please enable JavaScript\"\n- Added option to automatically insert placeholder input tables at the top of each page\n\n### Version 0.2.0\n\n- Added new input types (checkbox \u0026 dropdown menu)\n- Also allow numbers in placeholder names (everywhere except the first character)\n- Moved to typed mkdocs config (now requires mkdocs 1.4+)\n- Disable input elements for read only placeholders\n- Moved a lot of code around, significantly changed JavaScript file\n\n### Version 0.1.3\n\n- Placeholder config: Placeholders can now have attributes (like `description`)\n- Tables with inputs for all placeholders on a page can now be generated via `\u003cplaceholdertable\u003e` elements\n- Stack traces for fatal exceptions can now be seen with the `-v` flag (`mkdocs serve -v`)\n- When performing static replacements, the contents are now HTML escaped\n- Added script `mkdocs-placeholder-replace-static.py`\n\n### Version 0.1.2\n\n- Implemented static replacements for user-selected pages\n- Added timing options. This should  make it possible to use with MermaidJS diagrams, but may not always work\n\n### Version 0.1.1\n\n- Show a warning if an `input` element references a non-existent variable\n- Show a warning if a variable name does not match the recommended format\n- Perform type checks/conversions when loading placeholder data from the data file\n\n## Process for releases\n\nThis is just for me :)\n\n1. Run linters:\n    ```bash\n    mypy src\n    ```\n    ```bash\n    pyflakes src\n    ```\n\n    Check npm code with podman:\n    ```bash\n    podman run -it --rm --workdir /typescript -v \"$(pwd)/typescript:/typescript\" localhost/placeholder-npm:latest npm run lint\n    ```\n\n    Or with docker:\n    ```bash\n    docker run -it --rm --workdir /typescript -v \"$(pwd)/typescript:/typescript\" placeholder-npm:latest npm run lint\n    ```\n2. Update the changelog in this README file.\n3. Update version number in `./setup.cfg` and `typescript/src/api.ts`.\n4. Run `./build.sh` to compile the latest JavaScript code and test that it works. **`python -m build` will only build the latest Python code,** and incompatibilities between Python and JS code can break the release.\n4. Disable `debug_javascript` in `placeholder-plugin.yaml`.\n5. Build and update package.\n6. Create a commit for the release (`Version 0.X.Y`) and push it.\n7. Add a tag named `0.X.Y`:\n    ```bash\n    git tag 0.X.Y\n    ```\n8. Update the `latest-release` branch, so that the documentation website gets updated:\n    ```bash\n    git push\n    git branch --force latest-release HEAD\n    git push --tags origin latest-release\n    ```\n\n### Updating python dependencies\n\nIf you don't have them, install `pip-tools`:\n```bash\npython3 -m pip install pip-tools\n```\n\nThen update `requirements.txt`:\n```bash\npip-compile -U\n```\n\n### Updating npm dependencies\n\nThese are only used for the build process, so keeping them up to date is not that critical.\n\nStart a container with nodeJS:\n```bash\npodman run -it --rm -v \"$(pwd)/typescript:/mnt\" node:latest bash\n```\n\nIn the container run the following commands to update the `typescript/package*.json` files on the host:\n```bash\ncd /mnt\nnpm i -g npm-check-updates\nncu -u\nnpm i --package-lock-only\n```\n\nThen rebuild the docker image on the host:\n```bash\ncd typescript/\npodman build --tag placeholder-npm .\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsix-two%2Fmkdocs-placeholder-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsix-two%2Fmkdocs-placeholder-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsix-two%2Fmkdocs-placeholder-plugin/lists"}