From 59ae56c22e3316dc2dcb130fd136694febd00d52 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Wed, 11 Mar 2026 18:35:46 +0100 Subject: [PATCH 1/3] Replace "MkDocs" with "ProperDocs" Some references, such as references to old versions of MkDocs, are still left. docs/about/release-notes.md is not processed at all yet. This is because the historic info probably should still say the previous name. Maybe *some* of it should be changed, but that can be left until later. --- .gitignore | 2 +- CONTRIBUTING.md | 30 ++++---- README.md | 16 ++--- docs/about/release-notes.md | 4 +- docs/dev-guide/README.md | 6 +- docs/dev-guide/plugins.md | 30 ++++---- docs/dev-guide/themes.md | 68 +++++++++---------- docs/dev-guide/translations.md | 16 ++--- docs/getting-started.md | 20 +++--- docs/img/plugin-events.py | 2 +- docs/img/plugin-events.svg | 2 +- docs/index.md | 12 ++-- docs/user-guide/README.md | 4 +- docs/user-guide/choosing-your-theme.md | 10 +-- docs/user-guide/configuration.md | 58 ++++++++-------- docs/user-guide/customizing-your-theme.md | 6 +- docs/user-guide/deploying-your-docs.md | 16 ++--- docs/user-guide/installation.md | 10 +-- docs/user-guide/localizing-your-theme.md | 4 +- docs/user-guide/writing-your-docs.md | 56 +++++++-------- mkdocs.yml | 6 +- mkdocs/__main__.py | 16 ++--- mkdocs/commands/gh_deploy.py | 6 +- mkdocs/commands/new.py | 2 +- mkdocs/commands/serve.py | 2 +- mkdocs/config/base.py | 4 +- mkdocs/config/config_options.py | 4 +- mkdocs/config/defaults.py | 10 +-- mkdocs/contrib/search/__init__.py | 2 +- mkdocs/exceptions.py | 4 +- mkdocs/livereload/__init__.py | 2 +- mkdocs/plugins.py | 14 ++-- mkdocs/structure/__init__.py | 2 +- mkdocs/structure/files.py | 9 +-- mkdocs/structure/pages.py | 5 +- mkdocs/tests/build_tests.py | 4 +- mkdocs/tests/config/base_tests.py | 30 ++++---- .../config/config_options_legacy_tests.py | 2 +- mkdocs/tests/config/config_options_tests.py | 2 +- mkdocs/tests/config/config_tests.py | 4 +- mkdocs/tests/gh_deploy_tests.py | 8 +-- mkdocs/tests/integration.py | 8 +-- .../complicated_config/documentation/index.md | 2 +- .../tests/integration/minimal/docs/testing.md | 2 +- .../integration/subpages/docs/metadata.md | 2 +- .../unicode/docs/\303\234bersicht.md" | 2 +- .../integration/unicode/docs/\342\231\252.md" | 2 +- mkdocs/tests/structure/page_tests.py | 26 +++---- mkdocs/theme.py | 4 +- mkdocs/themes/mkdocs/base.html | 4 +- .../mkdocs/locales/de/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/es/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/fa/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/fr/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/id/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/it/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/ja/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/nb/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/nl/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/nn/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/pl/LC_MESSAGES/messages.po | 5 +- .../locales/pt_BR/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/ru/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/tr/LC_MESSAGES/messages.po | 5 +- .../mkdocs/locales/uk/LC_MESSAGES/messages.po | 5 +- .../locales/zh_CN/LC_MESSAGES/messages.po | 4 +- .../locales/zh_TW/LC_MESSAGES/messages.po | 5 +- mkdocs/themes/mkdocs/main.html | 4 +- mkdocs/themes/mkdocs/messages.pot | 5 +- mkdocs/themes/readthedocs/base.html | 2 +- mkdocs/themes/readthedocs/css/theme_extra.css | 2 +- mkdocs/themes/readthedocs/footer.html | 2 +- .../locales/de/LC_MESSAGES/messages.po | 5 +- .../locales/es/LC_MESSAGES/messages.po | 5 +- .../locales/fa/LC_MESSAGES/messages.po | 5 +- .../locales/fr/LC_MESSAGES/messages.po | 5 +- .../locales/id/LC_MESSAGES/messages.po | 5 +- .../locales/it/LC_MESSAGES/messages.po | 5 +- .../locales/ja/LC_MESSAGES/messages.po | 5 +- .../locales/nl/LC_MESSAGES/messages.po | 5 +- .../locales/pl/LC_MESSAGES/messages.po | 5 +- .../locales/pt_BR/LC_MESSAGES/messages.po | 5 +- .../locales/ru/LC_MESSAGES/messages.po | 5 +- .../locales/tr/LC_MESSAGES/messages.po | 5 +- .../locales/uk/LC_MESSAGES/messages.po | 5 +- .../locales/zh_CN/LC_MESSAGES/messages.po | 4 +- .../locales/zh_TW/LC_MESSAGES/messages.po | 5 +- mkdocs/themes/readthedocs/messages.pot | 5 +- mkdocs/utils/__init__.py | 2 +- mkdocs/utils/yaml.py | 2 +- 90 files changed, 358 insertions(+), 386 deletions(-) diff --git a/.gitignore b/.gitignore index cebf2abb..d68c3bfd 100644 --- a/.gitignore +++ b/.gitignore @@ -66,5 +66,5 @@ target/ venv/ ENV/ -# MkDocs documentation +# ProperDocs documentation site*/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 510ef6f6..76a4a343 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ -# Contributing to MkDocs +# Contributing to ProperDocs -An introduction to contributing to the MkDocs project. +An introduction to contributing to the ProperDocs project. -The MkDocs project welcomes contributions from developers and +The ProperDocs project welcomes contributions from developers and users in the open source community. Contributions can be made in a number of ways, a few examples are: @@ -16,7 +16,7 @@ GitHub repository. ## Reporting an Issue -Please include as much detail as you can. Let us know your platform and MkDocs +Please include as much detail as you can. Let us know your platform and ProperDocs version. If the problem is visual (for example a theme or design issue), please add a screenshot. If you get an error, please include the full error message and traceback. @@ -34,7 +34,7 @@ It is particularly helpful if an issue report touches on all of these aspects: ## Trying out the Development Version If you want to just install and try out the latest development version of -MkDocs (in case it already contains a fix for your issue), +ProperDocs (in case it already contains a fix for your issue), you can do so with the following command. This can be useful if you want to provide feedback for a new feature or want to confirm if a bug you have encountered is fixed in the git master. It is **strongly** recommended @@ -46,7 +46,7 @@ pip install git+https://github.com/mkdocs/mkdocs.git ## Installing for Development -Note that for development you can just use [Hatch] directly as described below. If you wish to install a local clone of MkDocs anyway, you can run `pip install --editable .`. It is **strongly** recommended that you do this within a [virtualenv]. +Note that for development you can just use [Hatch] directly as described below. If you wish to install a local clone of ProperDocs anyway, you can run `pip install --editable .`. It is **strongly** recommended that you do this within a [virtualenv]. ## Installing Hatch @@ -56,7 +56,7 @@ So first, [install it][install Hatch]. Ideally in an isolated way with **`pipx i ## Running all checks -To run **all** checks that are required for MkDocs, just run the following command in the cloned MkDocs repository: +To run **all** checks that are required for ProperDocs, just run the following command in the cloned ProperDocs repository: ```bash hatch run all @@ -68,7 +68,7 @@ All checks need to pass. ### Running tests -To run the test suite for MkDocs, run the following commands: +To run the test suite for ProperDocs, run the following commands: ```bash hatch run test:test @@ -81,7 +81,7 @@ will be verified by [GitHub Actions] when you submit a pull request. ### Python code style -Python code within MkDocs' code base is formatted using [Black] and [Isort] and lint-checked using [Ruff], all of which are configured in `pyproject.toml`. +Python code within ProperDocs' code base is formatted using [Black] and [Isort] and lint-checked using [Ruff], all of which are configured in `pyproject.toml`. You can automatically check and format the code according to these tools with the following command: @@ -103,7 +103,7 @@ There are several other checks, such as spelling and JS style. To run all of the hatch run lint:check ``` -### Documentation of MkDocs itself +### Documentation of ProperDocs itself After making edits to files under the `docs/` dir, you can preview the site locally using the following command: @@ -134,7 +134,7 @@ To localize a theme to your favorite language, follow the guide on [Translating ## Submitting Pull Requests -If you're considering a large code contribution to MkDocs, please prefer to +If you're considering a large code contribution to ProperDocs, please prefer to open an issue first to get early feedback on the idea. Once you think the code is ready to be reviewed, push @@ -148,7 +148,7 @@ Do *not* add to *release-notes.md*, this will be written later. ### Submitting changes to the builtin themes -When installed with `i18n` support (`pip install 'mkdocs[i18n]'`), MkDocs allows +When installed with `i18n` support (`pip install 'mkdocs[i18n]'`), ProperDocs allows themes to support being translated into various languages (referred to as locales) if they respect [Jinja's i18n extension] by wrapping text placeholders with `{% trans %}` and `{% endtrans %}` tags. @@ -159,8 +159,8 @@ updated by running the `extract_messages` command. To update the `pot` file for both built-in themes, run these commands: ```bash -pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs -pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs +pybabel extract --project=ProperDocs --copyright-holder=ProperDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs +pybabel extract --project=ProperDocs --copyright-holder=ProperDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs ``` The updated `pot` file should be included in a PR with the updated template. @@ -175,7 +175,7 @@ file so that everything is ready for translators to do their job. ## Code of Conduct -Everyone interacting in the MkDocs project's codebases, issue trackers, chat +Everyone interacting in the ProperDocs project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. [virtualenv]: https://virtualenv.pypa.io/en/latest/user_guide.html diff --git a/README.md b/README.md index 7b665a23..5e73d374 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# MkDocs +# ProperDocs > *Project documentation with Markdown* @@ -6,7 +6,7 @@ [![Build Status][GHAction-image]][GHAction-link] [![Coverage Status][codecov-image]][codecov-link] -MkDocs is a **fast**, **simple** and **downright gorgeous** static site +ProperDocs is a **fast**, **simple** and **downright gorgeous** static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with @@ -18,14 +18,14 @@ user guide. ## Features - Build static HTML files from Markdown files. -- Use Plugins and Markdown Extensions to enhance MkDocs. +- Use Plugins and Markdown Extensions to enhance ProperDocs. - Use the built-in themes, third party themes or create your own. - Publish your documentation anywhere that static files can be served. - Much more! ## Support -If you need help with MkDocs, do not hesitate to get in contact with us! +If you need help with ProperDocs, do not hesitate to get in contact with us! - For questions and high-level discussions, use **[Discussions]** on GitHub. - For small questions, a good alternative is the **[Chat room]** on @@ -33,7 +33,7 @@ If you need help with MkDocs, do not hesitate to get in contact with us! - To report a bug or make a feature request, open an **[Issue]** on GitHub. Please note that we may only provide -support for problems/questions regarding core features of MkDocs. Any +support for problems/questions regarding core features of ProperDocs. Any questions or bug reports about features of third-party themes, plugins, extensions or similar should be made to their respective projects. But, such questions are *not* banned from the [chat room]. @@ -46,15 +46,15 @@ Make sure to stick around to answer some questions as well! - [Latest Release Notes][release-notes] - [Catalog of third-party plugins, themes and recipes][catalog] -## Contributing to MkDocs +## Contributing to ProperDocs -The MkDocs project welcomes, and depends on, contributions from developers and +The ProperDocs project welcomes, and depends on, contributions from developers and users in the open source community. Please see the [Contributing Guide] for information on how you can help. ## Code of Conduct -Everyone interacting in the MkDocs project's codebases, issue trackers, and +Everyone interacting in the ProperDocs project's codebases, issue trackers, and discussion forums is expected to follow the [PyPA Code of Conduct]. diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 4fd81c15..8deb8140 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -4,7 +4,7 @@ ## Upgrading -To upgrade MkDocs to the latest version, use pip: +To upgrade ProperDocs to the latest version, use pip: ```bash pip install -U mkdocs @@ -19,7 +19,7 @@ mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10) ## Maintenance team -The current and past members of the MkDocs team. +The current and past members of the ProperDocs team. * [@tomchristie](https://github.com/tomchristie/) * [@d0ugal](https://github.com/d0ugal/) diff --git a/docs/dev-guide/README.md b/docs/dev-guide/README.md index 183365e0..8d262bc5 100644 --- a/docs/dev-guide/README.md +++ b/docs/dev-guide/README.md @@ -1,12 +1,12 @@ # Developer Guide -Extending MkDocs +Extending ProperDocs --- -The MkDocs Developer Guide provides documentation for developers of third +The ProperDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the [Contributing Guide] for information -on contributing to MkDocs itself. You can jump directly to a page listed +on contributing to ProperDocs itself. You can jump directly to a page listed below, or use the *next* and *previous* buttons in the navigation bar at the top of the page to move through the documentation in order. diff --git a/docs/dev-guide/plugins.md b/docs/dev-guide/plugins.md index e0305c3c..9ea98e96 100644 --- a/docs/dev-guide/plugins.md +++ b/docs/dev-guide/plugins.md @@ -1,21 +1,21 @@ -# MkDocs Plugins +# ProperDocs Plugins -A Guide to installing, using and creating MkDocs Plugins +A Guide to installing, using and creating ProperDocs Plugins --- ## Installing Plugins Before a plugin can be used, it must be installed on the system. If you are -using a plugin which comes with MkDocs, then it was installed when you installed -MkDocs. However, to install third party plugins, you need to determine the +using a plugin which comes with ProperDocs, then it was installed when you installed +ProperDocs. However, to install third party plugins, you need to determine the appropriate package name and install it using `pip`: ```bash pip install mkdocs-foo-plugin ``` -WARNING: Installing an MkDocs plugin means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing. +WARNING: Installing a ProperDocs plugin means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing. Once a plugin has been successfully installed, it is ready to use. It just needs to be [enabled](#using-plugins) in the configuration file. The [Catalog] @@ -56,9 +56,9 @@ For a list of default plugins and how to override them, see the ## Developing Plugins -Like MkDocs, plugins must be written in Python. It is generally expected that +Like ProperDocs, plugins must be written in Python. It is generally expected that each plugin would be distributed as a separate Python module, although it is -possible to define multiple plugins in the same module. At a minimum, a MkDocs +possible to define multiple plugins in the same module. At a minimum, a ProperDocs Plugin must consist of a [BasePlugin] subclass and an [entry point] which points to it. @@ -204,7 +204,7 @@ All `BasePlugin` subclasses contain the following method(s): #### load_config(options) Loads configuration from a dictionary of options. Returns a tuple of -`(errors, warnings)`. This method is called by MkDocs during configuration +`(errors, warnings)`. This method is called by ProperDocs during configuration validation and should not need to be called by the plugin. #### on_<event_name>() @@ -221,7 +221,7 @@ returns `None`), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as `**kwargs`. In the event that -additional keywords are provided to an event in a future version of MkDocs, +additional keywords are provided to an event in a future version of ProperDocs, there will be no need to alter your plugin. For example, the following event would add an additional static_template to @@ -441,7 +441,7 @@ Since MkDocs 1.4, plugins can choose to set a priority value for their events. E ### Handling Errors -MkDocs defines four error types: +ProperDocs defines four error types: #### ::: mkdocs.exceptions.MkDocsException @@ -454,7 +454,7 @@ MkDocs defines four error types: Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error -message. Therefore, MkDocs will catch any of the errors listed above, retrieve +message. Therefore, ProperDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user. @@ -486,7 +486,7 @@ class MyPlugin(BasePlugin): ### Logging in plugins -To ensure that your plugins' log messages adhere with MkDocs' formatting and `--verbose`/`--debug` flags, please write the logs to a logger under the `mkdocs.plugins.` namespace. +To ensure that your plugins' log messages adhere with ProperDocs' formatting and `--verbose`/`--debug` flags, please write the logs to a logger under the `mkdocs.plugins.` namespace. > EXAMPLE: > @@ -508,14 +508,14 @@ To ensure that your plugins' log messages adhere with MkDocs' formatting and `-- > NEW: **New in version 1.5** > -> MkDocs now provides a `get_plugin_logger()` convenience function that returns a logger like the above that is also prefixed with the plugin's name. +> ProperDocs now provides a `get_plugin_logger()` convenience function that returns a logger like the above that is also prefixed with the plugin's name. > > #### ::: mkdocs.plugins.get_plugin_logger ### Entry Point Plugins need to be packaged as Python libraries (distributed on PyPI separate -from MkDocs) and each must register as a Plugin via a setuptools `entry_points`. +from ProperDocs) and each must register as a Plugin via a setuptools `entry_points`. Add the following to your `setup.py` script: ```python @@ -543,7 +543,7 @@ entry_points={ ``` Note that registering a plugin does not activate it. The user still needs to -tell MkDocs to use it via the config. +tell ProperDocs to use it via the config. ### Publishing a Plugin diff --git a/docs/dev-guide/themes.md b/docs/dev-guide/themes.md index ea4b9911..f96dca78 100644 --- a/docs/dev-guide/themes.md +++ b/docs/dev-guide/themes.md @@ -6,7 +6,7 @@ A guide to creating and distributing custom themes. NOTE: If you are looking for existing third party themes, they are listed in the -[community wiki] page and the [MkDocs project catalog][catalog]. If you want to +[community wiki] page and the [ProperDocs project catalog][catalog]. If you want to share a theme you create, you should list it there. When creating a new theme, you can either follow the steps in this guide to @@ -15,7 +15,7 @@ basic, yet complete, theme with all the boilerplate required. **You can find this base theme on [GitHub][basic theme]**. It contains detailed comments in the code to describe the different features and their usage. -[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes +[community wiki]: https://github.com/mkdocs/mkdocs/wiki/ProperDocs-Themes [catalog]: https://github.com/mkdocs/catalog#-theming [basic theme]: https://github.com/mkdocs/mkdocs-basic-theme @@ -109,9 +109,9 @@ respectively. If you wish to write your own theme, it is recommended to start with one of the [built-in themes] and modify it accordingly. NOTE: -As MkDocs uses [Jinja] as its template engine, you have access to all the +As ProperDocs uses [Jinja] as its template engine, you have access to all the power of Jinja, including [template inheritance]. You may notice that the -themes included with MkDocs make extensive use of template inheritance and +themes included with ProperDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme [custom_dir]. Therefore, the built-in themes are implemented in a `base.html` file, which `main.html` extends. Although not @@ -125,7 +125,7 @@ themes for consistency. ### Picking up CSS and JavaScript from the config -MkDocs defines the top-level [extra_css](../user-guide/configuration.md#extra_css) and [extra_javascript](../user-guide/configuration.md#extra_javascript) configs. These are lists of files. +ProperDocs defines the top-level [extra_css](../user-guide/configuration.md#extra_css) and [extra_javascript](../user-guide/configuration.md#extra_javascript) configs. These are lists of files. The theme must include the HTML that links the items from these configs, otherwise the configs will be non-functional. You can see the recommended way to render both of them in the [base example above](#basic-theme). @@ -133,7 +133,7 @@ The theme must include the HTML that links the items from these configs, otherwi > > The items of the `config.extra_javascript` list used to be simple strings but now became objects that have these fields: `path`, `type`, `async`, `defer`. > -> In that version, MkDocs also gained the [`script_tag` filter](#script_tag). +> In that version, ProperDocs also gained the [`script_tag` filter](#script_tag). > > >? EXAMPLE: **Obsolete style:** > > @@ -200,7 +200,7 @@ the `mkdocs_theme.yml` configuration file and any Python files. ### Dot Files -Theme authors can explicitly force MkDocs to ignore files by starting a file or +Theme authors can explicitly force ProperDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: ```text @@ -231,7 +231,7 @@ The following variables are available globally on any template. #### config -The `config` variable is an instance of MkDocs' config object generated from the +The `config` variable is an instance of ProperDocs' config object generated from the `mkdocs.yml` config file. While you can use any config option, some commonly used options include: @@ -310,14 +310,14 @@ navigation as a nested list. #### base_url -The `base_url` provides a relative path to the root of the MkDocs project. While +The `base_url` provides a relative path to the root of the ProperDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the [url](#url) template filter, which is smarter about how it applies `base_url`. #### mkdocs_version -Contains the current MkDocs version. +Contains the current ProperDocs version. #### build_date_utc @@ -519,7 +519,7 @@ of those attributes as defined below: A `section` navigation object defines a named section in the navigation and contains a list of child navigation objects. Note that sections do not contain -URLs and are not links of any kind. However, by default, MkDocs sorts index +URLs and are not links of any kind. However, by default, ProperDocs sorts index pages to the top and the first child might be used as the URL for a section if a theme chooses to do so. @@ -570,7 +570,7 @@ The following attributes are available on `section` objects: #### Link A `link` navigation object contains a link which does not point to an internal -MkDocs page. +ProperDocs page. ::: mkdocs.structure.nav.Link options: @@ -657,7 +657,7 @@ And then displayed with this HTML in the custom theme. ## Template Filters In addition to [Jinja's default filters], the following custom filters are -available to use in MkDocs templates: +available to use in ProperDocs templates: ### url @@ -690,7 +690,7 @@ See how to use it in the [base example above](#basic-theme) ## Search and themes -As of MkDocs version *0.17* client side search support has been added to MkDocs +As of ProperDocs version *0.17* client side search support has been added to ProperDocs via the `search` plugin. A theme needs to provide a few things for the plugin to work with the theme. @@ -782,7 +782,7 @@ objects. If present, the `config` object contains the key/value pairs of config options defined for the plugin in the user's `mkdocs.yml` config file under -`plugings.search`. The `config` object was new in MkDocs version *1.0*. +`plugings.search`. The `config` object was new in ProperDocs version *1.0*. The `docs` object contains a list of document objects. Each document object is made up of a `location` (URL), a `title`, and `text` which can be used to create @@ -792,7 +792,7 @@ If present, the `index` object contains a pre-built index which offers performance improvements for larger sites. Note that the pre-built index is only created if the user explicitly enables the [prebuild_index] config option. Themes should expect the index to not be present, but can choose to use the -index when it is available. The `index` object was new in MkDocs version *1.0*. +index when it is available. The `index` object was new in ProperDocs version *1.0*. [Jinja2 template]: https://jinja.palletsprojects.com/ [built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes @@ -804,11 +804,11 @@ index when it is available. The `index` object was new in MkDocs version *1.0*. ## Packaging Themes -MkDocs makes use of [Python packaging] to distribute themes. This comes with a +ProperDocs makes use of [Python packaging] to distribute themes. This comes with a few requirements. -To see an example of a package containing one theme, see the [MkDocs Bootstrap -theme] and to see a package that contains many themes, see the [MkDocs +To see an example of a package containing one theme, see the [ProperDocs Bootstrap +theme] and to see a package that contains many themes, see the [ProperDocs Bootswatch theme]. NOTE: @@ -821,8 +821,8 @@ your theme, your users can more easily install it, they can rely on a default [custom_dir] to make tweaks to your theme to better suit their needs. [Python packaging]: https://packaging.python.org/en/latest/ -[MkDocs Bootstrap theme]: https://mkdocs.github.io/mkdocs-bootstrap/ -[MkDocs Bootswatch theme]: https://mkdocs.github.io/mkdocs-bootswatch/ +[ProperDocs Bootstrap theme]: https://mkdocs.github.io/mkdocs-bootstrap/ +[ProperDocs Bootswatch theme]: https://mkdocs.github.io/mkdocs-bootswatch/ ### Package Layout @@ -881,11 +881,11 @@ setup( Fill in the URL, license, description, author and author email address. The name should follow the convention `mkdocs-themename` (like -`mkdocs-bootstrap` and `mkdocs-bootswatch`), starting with MkDocs, using +`mkdocs-bootstrap` and `mkdocs-bootswatch`), starting with ProperDocs, using hyphens to separate words and including the name of your theme. Most of the rest of the file can be left unedited. The last section we need to -change is the entry_points. This is how MkDocs finds the theme(s) you are +change is the entry_points. This is how ProperDocs finds the theme(s) you are including in the package. The name on the left is the one that users will use in their mkdocs.yml and the one on the right is the directory containing your theme files. @@ -931,7 +931,7 @@ theme: show_sidebar: false ``` -In addition to arbitrary options defined by the theme, MkDocs defines a few +In addition to arbitrary options defined by the theme, ProperDocs defines a few special options which alters its behavior: > BLOCK: @@ -999,7 +999,7 @@ With the above changes, your theme should now be ready to install. This can be done with pip, using `pip install .` if you are still in the same directory as the setup.py. -Most Python packages, including MkDocs, are distributed on PyPI. To do this, +Most Python packages, including ProperDocs, are distributed on PyPI. To do this, you should run the following command. ```bash @@ -1027,7 +1027,7 @@ will experience consistent behavior regardless of the theme they may choose. The method for managing translations is up to the developers of a theme. However, if a theme developer chooses to use the same mechanisms used by the built-in themes, the sections below outline how to enable and make use of the -same commands utilized by MkDocs. +same commands utilized by ProperDocs. [localization/translation]: ../user-guide/localizing-your-theme.md @@ -1042,7 +1042,7 @@ available for use. The translation commands should be called from the root of your theme's working tree. -For an overview of the workflow used by MkDocs to translate the built-in +For an overview of the workflow used by ProperDocs to translate the built-in themes, see the appropriate [section] of the Contributing Guide and the [Translation Guide]. @@ -1054,7 +1054,7 @@ themes, see the appropriate [section] of the Contributing Guide and the > NOTE: If your theme inherits from an existing theme which already provides > translation catalogs, your theme's translations will be merged with the -> parent theme's translations during a MkDocs build. +> parent theme's translations during a ProperDocs build. > > This means that you only need to concentrate on the added translations. > Yet, you will still benefit from the translations of the parent theme. At @@ -1073,8 +1073,8 @@ Edit the templates by wrapping text in your HTML sources with --

This is an example theme for MkDocs.

-+

{% trans %}This is an example theme for MkDocs.{% endtrans %}

+-

This is an example theme for ProperDocs.

++

{% trans %}This is an example theme for ProperDocs.{% endtrans %}

It is designed to be read by looking at the theme HTML which is heavily @@ -1088,21 +1088,21 @@ running. While the Portable Object Template (`pot`) file created by the `extract_messages` command and the Portable Object (`po`) files created by the `init_catalog` and `update_catalog` commands are useful for creating and -editing translations, they are not used by MkDocs directly and do not need to -be included in a packaged release of a theme. When MkDocs builds a site with +editing translations, they are not used by ProperDocs directly and do not need to +be included in a packaged release of a theme. When ProperDocs builds a site with translations, it only makes use of the binary `mo` files(s) for the specified locale. Therefore, when [packaging a theme], make sure to include it in the "wheels", using a `MANIFEST.in` file or otherwise. Then, before building your Python package, you will want to ensure that the binary `mo` file for each locale is up-to-date by running the `compile_catalog` -command for each locale. MkDocs expects the binary `mo` files to be located at +command for each locale. ProperDocs expects the binary `mo` files to be located at `locales//LC_MESSAGES/messages.mo`, which the `compile_catalog` command automatically does for you. See [Testing theme translations] for details. NOTE: -As outlined in our [Translation Guide], the MkDocs project has chosen to +As outlined in our [Translation Guide], the ProperDocs project has chosen to include the `pot` and `po` files in our code repository, but not the `mo` files. This requires us to always run `compile_catalog` before packaging a new release regardless of whether any changes were made to a diff --git a/docs/dev-guide/translations.md b/docs/dev-guide/translations.md index 4c408b29..b36e374e 100644 --- a/docs/dev-guide/translations.md +++ b/docs/dev-guide/translations.md @@ -4,14 +4,14 @@ Theme localization guide. --- -The [built-in themes] that are included with MkDocs provide support for +The [built-in themes] that are included with ProperDocs provide support for translations. This is a guide for translators, which documents the process for contributing new translations and/or updating existing translations. For guidance on modifying the existing themes, see the [Contributing Guide][update themes]. To enable a specific translation see the documentation about the specific theme you are using in the [User Guide][built-in themes]. For translations of third-party themes, please see the documentation for those -themes. For a third-party theme to make use of MkDocs' translation tools and +themes. For a third-party theme to make use of ProperDocs' translation tools and methods, that theme must be properly [configured] to make use of those tools. NOTE: @@ -54,7 +54,7 @@ translation by following the steps below. Here is a quick summary of what you'll need to do: -1. [Fork and clone the MkDocs repository](#fork-and-clone-the-mkdocs-repository) and then [install MkDocs for development](../about/contributing.md#installing-for-development) for adding and testing translations. +1. [Fork and clone the ProperDocs repository](#fork-and-clone-the-mkdocs-repository) and then [install ProperDocs for development](../about/contributing.md#installing-for-development) for adding and testing translations. 2. [Initialize new localization catalogs](#initializing-the-localization-catalogs) for your language (if a translation for your locale already exists, follow the instructions for [updating theme localization files](#updating-the-translation-catalogs) instead). 3. [Add a translation](#translating-the-mkdocs-themes) for every text placeholder in the localized catalogs. 4. [Locally serve and test](#testing-theme-translations) the translated themes for your language. @@ -70,13 +70,13 @@ use of a term which differs from the general language translation. [ISO-639-1]: https://en.wikipedia.org/wiki/ISO_639-1 -### Fork and clone the MkDocs repository +### Fork and clone the ProperDocs repository -In the following steps you'll work with a fork of the MkDocs repository. Follow -the instructions for [forking and cloning the MkDocs +In the following steps you'll work with a fork of the ProperDocs repository. Follow +the instructions for [forking and cloning the ProperDocs repository](../about/contributing.md#installing-for-development). -To test the translations you also need to [install MkDocs for +To test the translations you also need to [install ProperDocs for development](../about/contributing.md#installing-for-development) from your fork. ### Initializing the localization catalogs @@ -150,7 +150,7 @@ text placeholder in the localized catalog. [add a translation]: #translating-the-mkdocs-themes -### Translating the MkDocs themes +### Translating the ProperDocs themes Now that your localized `messages.po` files are ready, all you need to do is add a translation in each `msgstr` item for each `msgid` item in the file. diff --git a/docs/getting-started.md b/docs/getting-started.md index 490b95d9..2aca4e4d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started with MkDocs +# Getting Started with ProperDocs An introductory tutorial! @@ -6,7 +6,7 @@ An introductory tutorial! ## Installation -To install MkDocs, run the following command from the command line: +To install ProperDocs, run the following command from the command line: ```bash pip install mkdocs @@ -26,14 +26,14 @@ cd my-project Take a moment to review the initial project that has been created for you. -![The initial MkDocs layout](img/initial-layout.png) +![The initial ProperDocs layout](img/initial-layout.png) There's a single configuration file named `mkdocs.yml`, and a folder named `docs` that will contain your documentation source files (`docs` is the default value for the [docs_dir] configuration setting). Right now the `docs` folder just contains a single documentation page, named `index.md`. -MkDocs comes with a built-in dev-server that lets you preview your documentation +ProperDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` configuration file, and then start the server by running the `mkdocs serve` command: @@ -50,7 +50,7 @@ INFO - [15:50:43] Serving on http://127.0.0.1:8000/ Open up in your browser, and you'll see the default home page being displayed: -![The MkDocs live server](img/screenshot.png) +![The ProperDocs live server](img/screenshot.png) The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme @@ -130,12 +130,12 @@ Save your changes, and you'll see the ReadTheDocs theme being used. ## Changing the Favicon Icon -By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create +By default, ProperDocs uses the [ProperDocs favicon] icon. To use a different icon, create an `img` subdirectory in the `docs` directory and copy your custom `favicon.ico` -file to that directory. MkDocs will automatically detect and use that file as your +file to that directory. ProperDocs will automatically detect and use that file as your favicon icon. -[MkDocs favicon]: img/favicon.ico +[ProperDocs favicon]: img/favicon.ico ## Building the site @@ -198,9 +198,9 @@ you're done. For specific instructions on a number of common hosts, see the ## Getting help -See the [User Guide] for more complete documentation of all of MkDocs' features. +See the [User Guide] for more complete documentation of all of ProperDocs' features. -To get help with MkDocs, please use the [GitHub discussions] or [GitHub issues]. +To get help with ProperDocs, please use the [GitHub discussions] or [GitHub issues]. [Installation Guide]: user-guide/installation.md [docs_dir]: user-guide/configuration.md#docs_dir diff --git a/docs/img/plugin-events.py b/docs/img/plugin-events.py index 0ad1f982..e032ee8d 100644 --- a/docs/img/plugin-events.py +++ b/docs/img/plugin-events.py @@ -7,7 +7,7 @@ from graphviz import Digraph -graph = Digraph("MkDocs", format="svg") +graph = Digraph("ProperDocs", format="svg") graph.attr(compound="true", bgcolor="transparent") graph.graph_attr.update(fontname="inherit", tooltip=" ") graph.node_attr.update(fontname="inherit", tooltip=" ", style="filled") diff --git a/docs/img/plugin-events.svg b/docs/img/plugin-events.svg index 6fc4702b..d9d42df1 100644 --- a/docs/img/plugin-events.svg +++ b/docs/img/plugin-events.svg @@ -1,7 +1,7 @@ -MkDocs +ProperDocs diff --git a/docs/index.md b/docs/index.md index f796a054..2cae79cf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,10 @@ -# MkDocs +# ProperDocs Project documentation with Markdown. --- -MkDocs is a **fast**, **simple** and **downright gorgeous** static site +ProperDocs is a **fast**, **simple** and **downright gorgeous** static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the [introductory tutorial], then check the @@ -27,13 +27,13 @@ configuration file. Start by reading the [introductory tutorial], then check the

Great themes available

- There's a stack of good looking themes available for MkDocs. + There's a stack of good looking themes available for ProperDocs. Choose between the built in themes: mkdocs and readthedocs, select one of the third-party themes - (on the MkDocs Themes wiki page - as well as the MkDocs Catalog), + (on the ProperDocs Themes wiki page + as well as the ProperDocs Catalog), or build your own.

@@ -77,7 +77,7 @@ configuration file. Start by reading the [introductory tutorial], then check the

Host anywhere

- MkDocs builds completely static HTML sites that you can host on + ProperDocs builds completely static HTML sites that you can host on GitHub Pages, Amazon S3, or anywhere else you choose. diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md index aea3ba83..65b7859d 100644 --- a/docs/user-guide/README.md +++ b/docs/user-guide/README.md @@ -1,10 +1,10 @@ # User Guide -Building Documentation with MkDocs +Building Documentation with ProperDocs --- -The MkDocs User Guide provides documentation for users of MkDocs. See +The ProperDocs User Guide provides documentation for users of ProperDocs. See [Getting Started] for an introductory tutorial. You can jump directly to a page listed below, or use the *next* and *previous* buttons in the navigation bar at the top of the page to move through the documentation in order. diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index 92d0eb65..496eecea 100644 --- a/docs/user-guide/choosing-your-theme.md +++ b/docs/user-guide/choosing-your-theme.md @@ -4,7 +4,7 @@ Selecting and configuring a theme. --- -MkDocs includes two built-in themes ([mkdocs](#mkdocs) and +ProperDocs includes two built-in themes ([mkdocs](#mkdocs) and [readthedocs](#readthedocs)), as documented below. However, many [third party themes] are available to choose from as well. @@ -19,7 +19,7 @@ theme: ## mkdocs The default theme, which was built as a custom [Bootstrap] theme, supports almost -every feature of MkDocs. +every feature of ProperDocs.