./textproc/py-mkdocs, Fast and simple static site generator for documentation

[ CVSweb ] [ Homepage ] [ RSS ] [ Required by ] [ Add to tracker ]

Branch: CURRENT, Version: 1.2.3, Package name: py39-mkdocs-1.2.3, Maintainer: pkgsrc-users

MkDocs 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.

Required to run:
[textproc/py-markdown] [textproc/py-yaml] [devel/py-setuptools] [textproc/py-jinja2] [lang/python27] [www/py-tornado] [devel/py-click] [www/py-livereload]

Required to build:

Master sites:

Filesize: 6148.302 KB

Version history: (Expand)

CVS history: (Expand)

   2022-02-05 10:44:04 by Adam Ciarcinski | Files touched by this commit (3) | Package updated
Log message:
py-mkdocs: updated to 1.2.3

Version 1.2.3 (2021-10-12)
Built-in themes now also support these languages:

Simplified Chinese
Brazilian Portuguese
Third-party plugins will take precedence over built-in plugins with the same name

Bugfix: Fix ability to load translations for some languages: core support

Bugfix (regression in 1.2): Prevent directory traversal in the dev server

Bugfix (regression in 1.2): Prevent webserver warnings from being treated as a \ 
build failure in strict mode

Bugfix: Correctly print colorful messages in the terminal on Windows

Bugfix: Python version 3.10 was displayed incorrectly in --version

Other small improvements; see commit log.

Version 1.2.2 (2021-07-18)
Bugfix (regression in 1.2): Fix serving files/paths with Unicode characters

Bugfix (regression in 1.2): Revert livereload file watching to use polling observer

This had to be done to reasonably support usages that span virtual filesystems \ 
such as non-native Docker and network mounts.

This goes back to the polling approach, very similar to that was always used \ 
prior, meaning most of the same downsides with latency and CPU usage.

Revert from 1.2: Remove the requirement of a site_url config and the restriction \ 
on use_directory_urls

Bugfix (regression in 1.2): Don't require trailing slash in the URL when serving \ 
a directory index in mkdocs serve server

Instead of showing a 404 error, detect if it's a directory and redirect to a \ 
path with a trailing slash added, like before.

Bugfix: Fix gh_deploy with config-file in the current directory

Bugfix: Fix reversed breadcrumbs in "readthedocs" theme

Allow "mkdocs.yaml" as the file name when '--config' is not passed

Stop treating ";" as a special character in URLs: urlparse -> urlsplit

Improve build performance for sites with many pages (partly already done in 1.2)

Version 1.2.1 (2021-06-09)
Bugfix (regression in 1.2): Ensure 'gh-deploy' always pushes.
Version 1.2 (2021-06-04)
Major Additions to Version 1.2
Support added for Theme Localization
The mkdocs and readthedocs themes now support language localization using the \ 
theme.locale parameter, which defaults to en (English). The only other supported \ 
languages in this release are fr (French) and es (Spanish). For details on using \ 
the provided translations, see the user guide. Note that translation will not \ 
happen by default. Users must first install the necessary dependencies with the \ 
following command:

pip install mkdocs[i18n]
Translation contributions are welcome and detailed in the Translation Guide.

Developers of third party themes may want to review the relevant section of the \ 
Theme Development Guide.

Contributors who are updating the templates to the built-in themes should review \ 
the Contributing Guide.

The lang setting of the search plugin now defaults to the language specified in \ 

Support added for Environment Variables in the configuration file
Environments variables may now be specified in the configuration file with the \ 
!ENV tag. The value of the variable will be parsed by the YAML parser and \ 
converted to the appropriate type.

somekey: !ENV VAR_NAME
otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value']
See Environment Variables in the Configuration documentation for details.

Support added for Configuration Inheritance
A configuration file may now inherit from a parent configuration file. In the \ 
primary file set the INHERIT key to the relative path of the parent file.

INHERIT: path/to/base.yml
The two files will then be deep merged. See Configuration Inheritance for details.

Update gh-deploy command
The vendored (and modified) copy of ghp_import has been replaced with a \ 
dependency on the upstream library. As of version 1.0.0, ghp-import includes a \ 
Python API which makes it possible to call directly.

MkDocs can now benefit from recent bug fixes and new features, including the \ 

A .nojekyll file is automatically included when deploying to GitHub Pages.
The --shell flag is now available, which reportedly works better on Windows.
Git author and committer environment variables should be respected
Rework auto-reload and HTTP server for mkdocs serve
mkdocs serve now uses a new underlying server + file watcher implementation, \ 
based on http.server from standard library and watchdog. It provides similar \ 
functionality to the previously used livereload library (which is now dropped \ 
from dependencies, along with tornado).

This makes reloads more responsive and consistent in terms of timing. Multiple \ 
rapid file changes no longer cause the site to repeatedly rebuild.

Almost every aspect of the server is slightly different, but actual visible \ 
changes are minor. The logging outputs are only similar to the old ones. \ 
Degradations in behavior are not expected, and should be reported if found.

Offset the local site root according to the sub-path of the site_url
When using mkdocs serve and having the site_url specified as e.g. \ 
http://example.org/sub/path/, now the root of the locally served site becomes \ and all document paths are offset accordingly.

A build_error event was added
Plugin developers can now use the on_build_error hook to execute code when an \ 
exception is raised while building the site.

See on_build_error in the Plugins documentation for details.

Three new exceptions: BuildError PluginError and Abort
MkDocs now has tree new exceptions defined in mkdocs.exceptions: BuildError, \ 
PluginError, and Abort:

PluginError can be raised from a plugin to stop the build and log an error \ 
message without traceback.
BuildError should not be used by third-party plugins developers and is reserved \ 
for internal use only.
Abort is used internally to abort the build and display an error without a traceback.
See Handling errors in the Plugins documentation for details.

Search Indexing Strategy configuration
Users can now specify which strategy they wish to use when indexing their site \ 
for search. A user can select between the following options:

full: Adds page title, section headings, and full page text to the search index.
sections: Adds page titles and section headings only to the search index.
titles: Adds only the page titles to the search index.
See Search Indexing in the configuration documentation for details.

Backward Incompatible Changes in 1.2
The site_url configuration option is now required. If it is not set, a warning \ 
will be issued. In a future release an error will be raised

The use_directory_urls configuration option will be forced to false if site_url \ 
is set to an empty string. In that case, if use_directory_urls is not explicitly \ 
set to false, a warning will be issued


This was reverted in release 1.2.2

The google_analytics configuration option is deprecated as Google appears to be \ 
phasing it out in favor of its new Google Analytics 4 property. See the \ 
documentation for your theme for alternatives which can be configured as part of \ 
your theme configuration. For example, the mkdocs and readthedocs themes have \ 
each added a new theme.analytics.gtag configuration option which uses the new \ 
Google Analytics 4 property. See Google's documentation on how to Upgrade to a \ 
Google Analytics 4 property. Then set theme.analytics.gtag to the "G-" \ 
ID and delete the  google_analytics configuration option which contains a \ 
"UA-" ID. So long as the old "UA-" ID and new "G-" \ 
ID are properly linked in your Google account, and you are using the \ 
"G-" ID, the data will be made available in both the old and new \ 
formats by Google Analytics.

A theme's files are now excluded from the list of watched files by default when \ 
using the --livereload server. This new default behavior is what most users need \ 
and provides better performance when editing site content. Theme developers can \ 
enable the old behavior with the --watch-theme option.

The mkdocs theme now removes the sidebar when printing a page. This frees up \ 
horizontal space for better rendering of content like tables

The mkdocs.config.DEFAULT_SCHEMA global variable has been replaced with the \ 
function mkdocs.config.defaults.get_schema(), which ensures that each instance \ 
of the configuration is unique

The mkdocs.utils.warning_filter is deprecated and now does nothing. Plugins \ 
should remove any reference to is as it may be deleted in a future release. To \ 
ensure any warnings get counted, simply log them to the mkdocs log (i.e.:  \ 

The on_serve event (which receives the server object and the builder function) \ 
is affected by the server rewrite. server is now a  \ 
mkdocs.livereload.LiveReloadServer instead of livereload.server.Server. The \ 
typical action that plugins can do with these is to call server.watch(some_dir, \ 
builder), which basically adds that directory to watched directories, causing \ 
the site to be rebuilt on file changes. That still works, but passing any other \ 
function to watch is deprecated and shows a warning. This 2nd parameter is \ 
already optional, and will accept only this exact builder function just for \ 

The python method of the plugins.search.prebuild_index configuration option is \ 
pending deprecation as of version 1.2. It is expected that in version 1.3 it \ 
will raise a warning if used and in version 1.4 it will raise an error. Users \ 
are encouraged to use an alternate method to generate a prebuilt index for \ 

The lunr and lunr[languages] dependencies are no longer installed by default. \ 
The dependencies are only needed for the rare user who pre-builds the search \ 
index and uses the python option, which is now pending deprecation. If you use \ 
this feature, then you will need to manually install lunr and lunr[languages]. A \ 
warning is issued if the dependencies are needed but not installed.

Other Changes and Additions to Version 1.2
Bugfix: Properly process navigation child items in _get_by_type when filtering \ 
for sections
Official support for Python 3.9 has been added and support for Python 3.5 has \ 
been dropped.
Bugfix: Fixes an issue that would result in a partially cut-off navigation item \ 
in the ReadTheDocs theme
Structure Files object now has a remove method to help plugin developers \ 
manipulate the Files tree. The corresponding src_paths has become a property to \ 
accommodate this possible dynamic behavior.
Updated highlight.js to 10.5.0.
Bugfix: Search plugin now works with Japanese language.
Documentation has been refactored
Restore styling of tables in the readthedocs theme
Ensure site_url ends with a slash
Correct documentation of pages template context variable
The lunr dependency has been updated to 0.5.9, and lunr.js to the corresponding \ 
2.3.9 version
Color is now used in log messages to identify errors, warnings and debug messages.
Bugfix: Identify homepage when use_directory_urls is False
   2022-01-31 10:48:36 by Thomas Klausner | Files touched by this commit (8)
Log message:
*: depend on py-click via versioned_dependencies
   2022-01-05 16:41:32 by Thomas Klausner | Files touched by this commit (289)
Log message:
python: egg.mk: add USE_PKG_RESOURCES flag

This flag should be set for packages that import pkg_resources
and thus need setuptools after the build step.

Set this flag for packages that need it and bump PKGREVISION.
   2022-01-04 21:55:40 by Thomas Klausner | Files touched by this commit (1595)
Log message:
*: bump PKGREVISION for egg.mk users

They now have a tool dependency on py-setuptools instead of a DEPENDS
   2021-11-01 22:05:56 by Thomas Klausner | Files touched by this commit (9)
Log message:
*: convert py-markdown users to versioned_dependencies.mk
   2021-10-26 13:23:42 by Nia Alarie | Files touched by this commit (1161)
Log message:
textproc: Replace RMD160 checksums with BLAKE2s checksums

All checksums have been double-checked against existing RMD160 and
SHA512 hashes

Unfetchable distfiles (fetched conditionally?):
./textproc/convertlit/distinfo clit18src.zip
   2021-10-07 17:02:49 by Nia Alarie | Files touched by this commit (1162)
Log message:
textproc: Remove SHA1 hashes for distfiles
   2018-10-03 12:33:25 by Adam Ciarcinski | Files touched by this commit (2) | Package updated
Log message:
py-mkdocs: updated to 1.0.4

Version 1.0.4:
Bugfix: Ignore absolute links in Markdown