-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Code updates and new functionality added * Removal of python-frontmatter * Importlib deprecation removal * Debugger documentation added --------- Co-authored-by: Maciej Kusz <9740637+mkusz@users.noreplay.github.com>
- Loading branch information
Showing
253 changed files
with
43,598 additions
and
10,358 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,64 +1,51 @@ | ||
--- | ||
date: 2023-02-28 12:30:18 | ||
update: 2023-06-12 23:52:23 | ||
--- | ||
# Publisher plugin for MkDocs | ||
# Publisher for MkDocs | ||
|
||
[![PyPI version](https://img.shields.io/pypi/v/mkdocs-publisher?logo=pypi&style=plastic)](https://pypi.org/project/mkdocs-publisher/) | ||
[![License type](https://img.shields.io/pypi/l/mkdocs-publisher?logo=pypi&style=plastic)](https://opensource.org/license/mit/) | ||
[![PyPI Downloads last month](https://img.shields.io/pypi/dm/mkdocs-publisher?logo=pypi&style=plastic)](https://pypistats.org/search/mkdocs-publisher) | ||
[![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-publisher?logo=python&style=plastic)](https://www.python.org) | ||
[![GitHub last commit](https://img.shields.io/github/last-commit/mkusz/mkdocs-publisher?logo=github&style=plastic)](https://github.com/mkusz/mkdocs-publisher/commits/main) | ||
|
||
Publishing platform plugins for [MkDocs](https://www.mkdocs.org/) that include: | ||
Publisher for [MkDocs](https://www.mkdocs.org/) is a set of plugins that helps with content creation and publication. | ||
|
||
- `pub-blog` – adds blogging capability, | ||
- `pub-social` – creates social cards for social media sharing using document metadata, | ||
- `pub-obsidian` - bindings for [Obsidina.md](https://obsidian.md) that allows you to use: | ||
- wikilinks, | ||
- backlinks, | ||
- callouts, | ||
- vega-charts (plugin), | ||
- `pub-minifier` – file size optimization (good for SEO and overall page size optimization), | ||
- `pub-meta` - support for documentation metadata (slug, dates, publication status, directories publication status, automatic navigation building, etc.). | ||
## Features | ||
|
||
- [pub-meta](https://mkusz.github.io/mkdocs-publisher/setup/general/pub-meta/) – support for: | ||
- automatic [document navigation](https://www.mkdocs.org/user-guide/configuration/#nav) creation based on file names order, | ||
- document publication status, | ||
- possibility to define document and directories URL (good for SEO), | ||
- document creation and update date (good for SEO), | ||
- [pub-blog](https://mkusz.github.io/mkdocs-publisher/setup/general/pub-blog/) – blogging capability: | ||
- index creation, | ||
- support for blog post teasers, | ||
- automatic creation of pages for archive, categories and tags, | ||
- [pub-obsidian](https://mkusz.github.io/mkdocs-publisher/setup/general/pub-obsidian/) – bindings for [Obsidina.md](https://obsidian.md) that allows you to use: | ||
- [backlinks](https://help.obsidian.md/Plugins/Backlinks), | ||
- [callouts](https://help.obsidian.md/Editing+and+formatting/Callouts), | ||
- [wikilinks](https://help.obsidian.md/Linking+notes+and+files/Internal+links), | ||
- [vega charts](https://vega.github.io/vega/) (using [Vega Visualization Plugin for Obsidian](https://github.com/Some-Regular-Person/obsidian-vega)) - advanced solution for creating charts, | ||
- [pub-social](https://mkusz.github.io/mkdocs-publisher/setup/seo-and-sharing/pub-social/) – social cards for social media sharing using document metadata, | ||
- [pub-minifier](https://mkusz.github.io/mkdocs-publisher/setup/seo-and-sharing/pub-minifier/) – file size optimization (good for SEO and overall page size optimization), | ||
- [pub-debugger](https://mkusz.github.io/mkdocs-publisher/setup/development/pub-debugger/) – logging on steroids with the possibility of creating of ZIP file with logs and additional information (can be used for better issue reporting). | ||
|
||
## Installation | ||
|
||
```commandline | ||
pip install mkdocs-publisher | ||
``` | ||
|
||
## Basic usage | ||
|
||
> **Note** | ||
> As a base for any development, [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme was used. If you are willing to use any other theme, you may (or may not) face some issues. If this happens, please submit an [issue](https://github.com/mkusz/mkdocs-publisher/issues). | ||
More information about installation methods and plugin setup can be found on this [documentation page](https://mkusz.github.io/mkdocs-publisher/setup/installation/). | ||
|
||
> **Warning** | ||
> Consider this plugin as a beta, so before any use make sure you have a backup of your data. | ||
If you have found any issue, have an idea for a feature, please submit an issue. | ||
> Before any use make sure you have a backup of your data. | ||
## Features | ||
|
||
List of included features (more documentation is needed): | ||
|
||
- automatic blog post index page generation with blog post teasers based on delimiter inside a blog post and own template (delimiter can be changed in plugin config in `mkdocs.yaml`), | ||
- blog post/page update date based on blog post metadata, | ||
- separate directory for blog post documents with auto-generated separate navigation (blog posts are sorted from newest to oldest based on blog post metadata), | ||
- home page set to blog post index with possibility to rename, | ||
- auto-adding link to full blog post from blog post index file (under each post that has teaser delimiter, if delimiter is not present, then full post is inside post index file, but is preserved in blog post navigation and site map), | ||
- added sub-pages for blog posts: archive, categories, tags, | ||
- minification plugin for graphics and documentation files, | ||
- social cards metadata injection based on document metadata (no need to edit any template). | ||
|
||
## How To | ||
|
||
More detailed information on how to set up, configure and write a blog posts and/or documentation can be found in [documentation](https://mkusz.github.io/mkdocs-publisher/) . | ||
> **Note** | ||
> As a base for any development, [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme was used. If you are willing to use any other theme, you may (or may not) face some issues. If this happens, please submit an [issue](https://github.com/mkusz/mkdocs-publisher/issues). | ||
## Planned features | ||
|
||
A full list of planned developments can be found on [this documentation page](https://mkusz.github.io/mkdocs-publisher/development/backlog/). I'm planning to move it to the project [GitHub issues](https://github.com/mkusz/mkdocs-publisher/issues) with proper badges and longer descriptions, but it's time-consuming and at this stage I'd rather spend it to develop a project. | ||
A full list of planned developments can be found on [this documentation page](https://mkusz.github.io/mkdocs-publisher/development/other/backlog/). I'm planning to move it to the project [GitHub issues](https://github.com/mkusz/mkdocs-publisher/issues) with proper badges and longer descriptions, but it's time-consuming and at this stage I'd rather spend it to develop a project. | ||
|
||
## Version history | ||
|
||
This section becomes too big and hard to navigate. Also it's harder to maintain the same changelog in 2 places. The entire version history can be found in the project [version history](https://mkusz.github.io/mkdocs-publisher/development/changelog/) document and on inside project [GitHub releases](https://github.com/mkusz/mkdocs-publisher/releases). | ||
The entire version history can be found in the project [version history](https://mkusz.github.io/mkdocs-publisher/development/changelog/) document and inside [releases](https://github.com/mkusz/mkdocs-publisher/releases). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.