Package: mkdocs-placeholder-plugin
MkDocs Placeholder PluginThis plugin allows you to have placeholders in your site, that can be dynamically replaced at runtime using JavaScript (seedemo page).DocumentationThis README is just a short intro to the package.
For a quick start and detailed information please see thedocumentation for the last release.
The documentation is also available in thedocsfolder of the source code and can be built locally withMkDocs.Development versionIf you want to use the latest development version (may be broken/buggy from time to time), you can install it by:Cloning the repository:gitclonehttps://github.com/six-two/mkdocs-placeholder-plugincdmkdocs-placeholder-pluginBuilding/Downloading the JavaScript files.
Choose any of the following ways:Build it with npm (natively), by running the./build-docs.shscript.Build it in a (docker/podman) container by using theDockerfilein thetypescriptdirectory.
The whole thing can be done by running thebuils.shscript in the root directory:./build.shOnce you see mkdocs running, you can terminate it withCtrl-C.Downloading the files from the development version of the documentation (hosted and built by Vercel):curlhttps://dev.mkdocs-placeholder-plugin.six-two.dev/assets/javascripts/placeholder.min.js-osrc/mkdocs_placeholder_plugin/assets/placeholder.min.js
curlhttps://dev.mkdocs-placeholder-plugin.six-two.dev/assets/javascripts/placeholder.min.js.map-osrc/mkdocs_placeholder_plugin/assets/placeholder.min.js.mapInstalling the package with pip:python3-mpipinstall.The corresponding documentation is hosted athttps://dev.mkdocs-placeholder-plugin.six-two.dev.Notable changesVersion 0.4.1Validators can copy rules from other validators via theimport_rules_fromattributeNew validators:email,linux_interface,mac_address,uuidVersion 0.4.0Configuration format changed:Validators are no longer defined in-line and instead defined in avalidatorssection -> easier to reuse custom validators.Placeholders now need to be specified in aplaceholderssection.Most settings are now in the configuration file instead of in yourmkdocs.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.1RemovedApply all changesbuttons. Seeissue #3Version 0.3.0This 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 smallerShould 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 fasterNested placeholders (placeholders that contain placeholders that contain placeholder...) no longer need to be specified in a speific order in the configuration file.A placeholder'sdefault-functionand a validator rule'smatch_functionare now evaluated usingnew Function(...)instead ofeval(...), so you need to add a return statement.Version 0.2.5When an JavaScript generatedauto-input-tableis empty, now a info box is shown (instead of nothing / an empty table).Bugfixes:auto_placeholder_tables_javascripthad no effect.PressingEnteron text fields without validators did not try to reload the page,Version 0.2.4Added 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_httpCustom validators with rules that either useregexormatch_functionAddedplaceholder_extra_jsfield to plugin configuration (for loading custom functions)Addeddefault-functionattribute for placeholdersVersion 0.2.3Split JavaScript code into multiple files and made it available via the globalPlaceholderDataandPlaceholderPluginobjects.
These interfaces are not stable, so you should probably not try to rely on them to much.Addedreplace_everywhereattribute for placeholdersChanges to textbox values are only stored, when you pressEnterDynamically generated tables now honoradd_apply_table_columnImproved JavaScript debugging: timestamps, more messages, and you can disable the page reloadSome visual fixes, mainly for theMaterial for MkDocsthemeVersion 0.2.2Improved 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 elementsProperly handle checkboxes and dropdown menus when performing static replacementsHide JavaScript console output by defaultGenerate automatic placeholder table dynamically, since if checkboxes / dropdowns are used, it can not be predicted, which values are used on the page.Addeddescription-or-namecolumn type to placeholder tables.Version 0.2.1Add option to reload the page if a checkbox/dropdown is changed or a text field is changed andEnteris 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 pageVersion 0.2.0Added 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 placeholdersMoved a lot of code around, significantly changed JavaScript fileVersion 0.1.3Placeholder config: Placeholders can now have attributes (likedescription)Tables with inputs for all placeholders on a page can now be generated via<placeholdertable>elementsStack traces for fatal exceptions can now be seen with the-vflag (mkdocs serve -v)When performing static replacements, the contents are now HTML escapedAdded scriptmkdocs-placeholder-replace-static.pyVersion 0.1.2Implemented static replacements for user-selected pagesAdded timing options. This should  make it possible to use with MermaidJS diagrams, but may not always workVersion 0.1.1Show a warning if aninputelement references a non-existent variableShow a warning if a variable name does not match the recommended formatPerform type checks/conversions when loading placeholder data from the data fileProcess for releasesThis is just for me :)Run linters:mypy srcpyflakes srcUpdate the changelog in this README file.Update version number insetup.cfg.Disabledebug_javascriptinplaceholder-plugin.yaml.Build and update package.Create a commit for the release (Version 0.X.Y) and push it.Add a tag named0.X.Y:git tag 0.X.YUpdate thelatest-releasebranch, so that the documentation website gets updated:git branch --force latest-release HEAD
git push --tags origin latest-releaseUpdating python dependenciesIf you don't have them, installpip-tools:python3-mpipinstallpip-toolsThen updaterequirements.txt:pip-compile-UUpdating npm dependenciesThese are only used for the build process, so keeping them up to date is not that critical.Start a container with nodeJS:podmanrun-it--rm-v"$(pwd)/typescript:/mnt"node:latestbashIn the container run the following commands to update thetypescript/package*.jsonfiles on the host:cd/mnt
npmi-gnpm-check-updates
ncu-u
npmi--package-lock-onlyThen rebuild the docker image on the host:cdtypescript/
podmanbuild--tagplaceholder-npm.