# MkDocs Placeholder Plugin
[](https://pypi.org/project/mkdocs-placeholder-plugin/)
This 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/)).
## Documentation
This README is just a short intro to the package.
For a quick start and detailed information please see the [documentation for the last release](https://mkdocs-placeholder-plugin.six-two.dev/).
The documentation is also available in the `docs` folder of the source code and can be built locally with [MkDocs](https://www.mkdocs.org/).
## Development version
If you want to use the latest development version (may be broken/buggy from time to time), you can install it by:
1. Cloning the repository:
```bash
git clone https://github.com/six-two/mkdocs-placeholder-plugin
cd mkdocs-placeholder-plugin
```
2. Building/Downloading the JavaScript files.
Choose any of the following ways:
- Build it with npm (natively), by running the `./build-docs.sh` script.
- Build it in a (docker/podman) container by using the `Dockerfile` in the `typescript` directory.
The whole thing can be done by running the `buils.sh` script in the root directory:
```bash
./build.sh
```
Once you see mkdocs running, you can terminate it with `Ctrl-C`.
- Downloading the files from the development version of the documentation (hosted and built by Vercel):
```bash
curl https://dev.mkdocs-placeholder-plugin.six-two.dev/placeholder.min.js -o src/mkdocs_placeholder_plugin/assets/placeholder.min.js
curl https://dev.mkdocs-placeholder-plugin.six-two.dev/placeholder.min.js.map -o src/mkdocs_placeholder_plugin/assets/placeholder.min.js.map
```
3. Installing the package with pip:
```bash
python3 -m pip install .
```
The corresponding documentation is hosted at <https://dev.mkdocs-placeholder-plugin.six-two.dev>.
## Notable changes
### Version 0.5.0
- Added inline editable placeholders (see [#6](https://github.com/six-two/mkdocs-placeholder-plugin/issues/6)) and enabled them by default:
- If you want to disable them by default, add `inline_editors: false` to the `settings` attribute in your `placeholder-plugin.yaml`.
- 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`.
- You can choose how inline placeholders look via the [`inline_editor_style` setting](https://mkdocs-placeholder-plugin.six-two.dev/configuration/#inline_editor_style).
- You can now embed the placeholder settings editor anywhere if your page with `<div class="placeholder-settings-panel"></div>`.
### Version 0.4.1
- Validators can copy rules from other validators via the `import_rules_from` attribute
- New validators: `email`, `linux_interface`, `mac_address`, `uuid`
### Version 0.4.0
- Configuration format changed:
- Validators are no longer defined in-line and instead defined in a `validators` section -> easier to reuse custom validators.
- Placeholders now need to be specified in a `placeholders` section.
- Most settings are now in the configuration file instead of in your `mkdocs.yml`.
- 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.
- (By default) values are saved when the focus leaves a text field.
- Removed static placeholder input tables (`<placeholdertable>`).
- Uncoupled the code from MkDocs.
You should now be able to relatively easy port the project to other Markdown based static site generators if you want to.
### Version 0.3.1
- Removed `Apply all changes` buttons. See [issue #3](https://github.com/six-two/mkdocs-placeholder-plugin/issues/3)
### Version 0.3.0
This release may be a bit buggy due to the rewrite and the documentation is not entirely accurate yet.
I will update the docs after I also clean up / rewrite the python code (planed for v0.4.0).
- Rewrote the JavaScript code in TypeScript:
- Packed and minified using Webpack, so the file is a bit smaller
- Should find stupid errors I make in code paths that I do not test (often)
- 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
- Nested placeholders (placeholders that contain placeholders that contain placeholder...) no longer need to be specified in a speific order in the configuration file.
- 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.
### Version 0.2.5
- When an JavaScript generated `auto-input-table` is empty, now a info box is shown (instead of nothing / an empty table).
- Bugfixes:
- `auto_placeholder_tables_javascript` had no effect.
- Pressing `Enter` on text fields without validators did not try to reload the page,
### Version 0.2.4
- Added input validation:
- 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`
- Custom validators with rules that either use `regex` or `match_function`
- Added `placeholder_extra_js` field to plugin configuration (for loading custom functions)
- Added `default-function` attribute for placeholders
### Version 0.2.3
- Split JavaScript code into multiple files and made it available via the global `PlaceholderData` and `PlaceholderPlugin` objects.
These interfaces are not stable, so you should probably not try to rely on them to much.
- Added `replace_everywhere` attribute for placeholders
- Changes to textbox values are only stored, when you press `Enter`
- Dynamically generated tables now honor `add_apply_table_column`
- Improved JavaScript debugging: timestamps, more messages, and you can disable the page reload
- Some visual fixes, mainly for the `Material for MkDocs` theme
### Version 0.2.2
- Improved placeholder input tables:
- Can now specify which columns to use (and their order)
- Only show apply values column, if at least one column contains input elements
- Properly handle checkboxes and dropdown menus when performing static replacements
- Hide JavaScript console output by default
- Generate automatic placeholder table dynamically, since if checkboxes / dropdowns are used, it can not be predicted, which values are used on the page.
- Added `description-or-name` column type to placeholder tables.
### Version 0.2.1
- 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).
This is enabled by default.
- Set initial value for placeholder input fields to "Please enable JavaScript"
- Added option to automatically insert placeholder input tables at the top of each page
### Version 0.2.0
- Added new input types (checkbox & dropdown menu)
- Also allow numbers in placeholder names (everywhere except the first character)
- Moved to typed mkdocs config (now requires mkdocs 1.4+)
- Disable input elements for read only placeholders
- Moved a lot of code around, significantly changed JavaScript file
### Version 0.1.3
- Placeholder config: Placeholders can now have attributes (like `description`)
- Tables with inputs for all placeholders on a page can now be generated via `<placeholdertable>` elements
- Stack traces for fatal exceptions can now be seen with the `-v` flag (`mkdocs serve -v`)
- When performing static replacements, the contents are now HTML escaped
- Added script `mkdocs-placeholder-replace-static.py`
### Version 0.1.2
- Implemented static replacements for user-selected pages
- Added timing options. This should make it possible to use with MermaidJS diagrams, but may not always work
### Version 0.1.1
- Show a warning if an `input` element references a non-existent variable
- Show a warning if a variable name does not match the recommended format
- Perform type checks/conversions when loading placeholder data from the data file
## Process for releases
This is just for me :)
1. Run linters:
```bash
mypy src
```
```bash
pyflakes src
```
Check npm code with podman:
```bash
podman run -it --rm --workdir /typescript -v "$(pwd)/typescript:/typescript" localhost/placeholder-npm:latest npm run lint
```
Or with docker:
```bash
docker run -it --rm --workdir /typescript -v "$(pwd)/typescript:/typescript" placeholder-npm:latest npm run lint
```
2. Update the changelog in this README file.
3. Update version number in `./setup.cfg` and `typescript/src/api.ts`.
4. Run `./build.sh` to compile the latest JavaScript code and test that it works.
4. Disable `debug_javascript` in `placeholder-plugin.yaml`.
5. Build and update package.
6. Create a commit for the release (`Version 0.X.Y`) and push it.
7. Add a tag named `0.X.Y`:
```bash
git tag 0.X.Y
```
8. Update the `latest-release` branch, so that the documentation website gets updated:
```bash
git push
git branch --force latest-release HEAD
git push --tags origin latest-release
```
### Updating python dependencies
If you don't have them, install `pip-tools`:
```bash
python3 -m pip install pip-tools
```
Then update `requirements.txt`:
```bash
pip-compile -U
```
### Updating npm dependencies
These are only used for the build process, so keeping them up to date is not that critical.
Start a container with nodeJS:
```bash
podman run -it --rm -v "$(pwd)/typescript:/mnt" node:latest bash
```
In the container run the following commands to update the `typescript/package*.json` files on the host:
```bash
cd /mnt
npm i -g npm-check-updates
ncu -u
npm i --package-lock-only
```
Then rebuild the docker image on the host:
```bash
cd typescript/
podman build --tag placeholder-npm .
```
Raw data
{
"_id": null,
"home_page": "https://github.com/six-two/mkdocs-placeholder-plugin",
"name": "mkdocs-placeholder-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "six-two",
"author_email": "pip@six-two.dev",
"download_url": "https://files.pythonhosted.org/packages/6d/c8/8d7207a5ad21983f4cee90c7771a48bf8505805a792f6364f68a7d440209/mkdocs_placeholder_plugin-0.5.0.post1.tar.gz",
"platform": null,
"description": "# MkDocs Placeholder Plugin\n\n[](https://pypi.org/project/mkdocs-placeholder-plugin/)\n\n\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 <https://dev.mkdocs-placeholder-plugin.six-two.dev>.\n\n## Notable changes\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 if your page with `<div class=\"placeholder-settings-panel\"></div>`.\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 -> 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 (`<placeholdertable>`).\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 & 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 `<placeholdertable>` 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.\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",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Add dynamic placeholders to your mkdocs page",
"version": "0.5.0.post1",
"project_urls": {
"Homepage": "https://github.com/six-two/mkdocs-placeholder-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a9e965fbd45a892b7fcda44e37158aeff6818f0888ad283ffd595ca899bb8ec9",
"md5": "4555f7278f750cd55e2a6fe4477e494d",
"sha256": "5650e54f7d105f5215e7b4a685f1c65c2573a9eaf216b3c772976a5dc220f47f"
},
"downloads": -1,
"filename": "mkdocs_placeholder_plugin-0.5.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4555f7278f750cd55e2a6fe4477e494d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 93704,
"upload_time": "2024-06-19T17:26:02",
"upload_time_iso_8601": "2024-06-19T17:26:02.938483Z",
"url": "https://files.pythonhosted.org/packages/a9/e9/65fbd45a892b7fcda44e37158aeff6818f0888ad283ffd595ca899bb8ec9/mkdocs_placeholder_plugin-0.5.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6dc88d7207a5ad21983f4cee90c7771a48bf8505805a792f6364f68a7d440209",
"md5": "4aa74106a1d120ebf4cf079933de7229",
"sha256": "a281b0e8e800fdaba80e86e0fe96dd15670aa1fdb8f97a920f917a3a15e2cada"
},
"downloads": -1,
"filename": "mkdocs_placeholder_plugin-0.5.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "4aa74106a1d120ebf4cf079933de7229",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 86277,
"upload_time": "2024-06-19T17:26:06",
"upload_time_iso_8601": "2024-06-19T17:26:06.941834Z",
"url": "https://files.pythonhosted.org/packages/6d/c8/8d7207a5ad21983f4cee90c7771a48bf8505805a792f6364f68a7d440209/mkdocs_placeholder_plugin-0.5.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-19 17:26:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "six-two",
"github_project": "mkdocs-placeholder-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mkdocs-placeholder-plugin"
}
JSON
