# mkdocs-annexes-integration
This is a plugin that transforms annex files into images or code blocks to be integrated in Markdown pages for MkDocs.
## Setup
### Before installing
Before installing this plugin you need to install `poppler-utils` as it is used by `pdf2image` that is required to use this plugin.
#### Install on Linux :
Note: *It depend on your Linux OS*
``` sh
sudo apt-get install poppler-utils
```
``` sh
sudo yum install poppler-utils
```
#### Install on MacOS :
``` sh
brew install poppler
```
#### Install on Windows :
On Windows, you can download the latest binary release of Poppler from the official website and extract the files to a folder. Then, add the folder to the system's PATH environment variable.
### Installing using pip:
`pip install mkdocs-annexes-integration`
## Config
You need to activate the plugin in `mkdocs.yml`:
```yaml
plugins:
- annexes-integration:
annexes: # Required (at least 1)
- Title of the annex A1: path/A/to/an/annex1.pdf # A path to an annex with it's title
- Title of the annex A2: path/A/to/an/annex2.pdf # Another path to an annex in same folder as the first
- Title of the annex B1: path/B/to/an/annex1.pdf # Another path to an annex but in different folder as the first two
- Title of the code file annex:
src: ../src/path/to/a/code/file.py
dest: dest/path/to/a/code/file.py
- Title of the code directory annex:
src: ../src/path/to/a/code/directory
dest: dest/path/to/a/code/directory
# others annexes...
temp_dir: "folder_name" # Optional --> Default : temp_annexes
enabled_if_env: ENABLE_ANNEXES_INTEGRATION # Optional
```
As you can see, there are two possible ways to integrate an annex: using a simple path or a source path and a destination path. **Both paths need to be relative to `docs_dir`, though**.
Set at least one annex to use this plugin. If you don't have any annex don't add this plugin to the mkdocs plugins list in config file mkdocs.yml
- `annexes` - A list of all the annexes documents. The path from `docs_dir` to an annex file or directory associated to it's title. Each file in a directory will integrated in subsection of the same document with a heading 2 containing the relative path of the file from the given directory.
- `temp_dir` - The temp directory used to generate markdown file for each annex before rendering to HTML. Only set this option if you already have a temp_annexes folder in the root directory (same as mkdocs.yml), which, you should not normally.
- `enabled_if_env` - Setting this option will enable the build only if there is an environment variable set to 1. Integrations of PDF can slow down build process and it's pretty useful to be fast when doing modification to mkdocs files when doing mkdocs serve.
## Usage
Using the command `mkdocs build` or `mkdocs serve` will trigger the plugin if it as been set correctly in config file.
This plugin is intended to be used with `mkdocs-with-pdf` plugin but can be used as it is.
## Support
This plugin currently support two type of files :
- **PDF files**: The plugin will convert each page of the PDF into images to be integrated on a page
- **Code files**: The plugin will put the content of the code file into a codeblock to be integrated on a page
Currently supported code files are :
- CSharp (.cs)
- CSS (.css)
- Dart (.dart)
- HTML (.html)
- Javascript (.js)
- JSON (.json)
- PHP (.php)
- Python (.py)
## License
This project is under MIT license see: `license` file for more detail.
## See Also
- [gitlab repo](http://www.gitlab.org/cfpt-mkdocs-plugins/mkdocs-annexes-integration/)
- [mkdocs website](http://www.mkdocs.org/)
- [mkdocs with-pdf plugin](https://github.com/orzih/mkdocs-with-pdf)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/cfpt-mkdocs-plugins/mkdocs-annexes-integration",
"name": "mkdocs-annexes-integration",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "mkdocs",
"author": "Thibaud Briard",
"author_email": "thibaud.brrd@eduge.ch",
"download_url": "https://files.pythonhosted.org/packages/ae/84/810e995b2cf3950030fef9333e30d7cce21a88ba6725b6de77e84c3e67d7/mkdocs-annexes-integration-0.1.5.tar.gz",
"platform": null,
"description": "# mkdocs-annexes-integration\n\nThis is a plugin that transforms annex files into images or code blocks to be integrated in Markdown pages for MkDocs.\n\n## Setup\n\n### Before installing\n\nBefore installing this plugin you need to install `poppler-utils` as it is used by `pdf2image` that is required to use this plugin.\n\n#### Install on Linux :\n\nNote: *It depend on your Linux OS*\n\n``` sh\nsudo apt-get install poppler-utils\n```\n\n``` sh\nsudo yum install poppler-utils\n```\n\n#### Install on MacOS :\n\n``` sh\nbrew install poppler\n```\n\n#### Install on Windows :\n\nOn Windows, you can download the latest binary release of Poppler from the official website and extract the files to a folder. Then, add the folder to the system's PATH environment variable.\n\n### Installing using pip:\n\n`pip install mkdocs-annexes-integration`\n\n## Config\n\nYou need to activate the plugin in `mkdocs.yml`:\n\n```yaml\nplugins:\n - annexes-integration:\n annexes: # Required (at least 1)\n - Title of the annex A1: path/A/to/an/annex1.pdf # A path to an annex with it's title\n - Title of the annex A2: path/A/to/an/annex2.pdf # Another path to an annex in same folder as the first\n - Title of the annex B1: path/B/to/an/annex1.pdf # Another path to an annex but in different folder as the first two\n - Title of the code file annex:\n src: ../src/path/to/a/code/file.py\n dest: dest/path/to/a/code/file.py\n - Title of the code directory annex:\n src: ../src/path/to/a/code/directory\n dest: dest/path/to/a/code/directory\n # others annexes...\n temp_dir: \"folder_name\" # Optional --> Default : temp_annexes\n enabled_if_env: ENABLE_ANNEXES_INTEGRATION # Optional\n```\n\nAs you can see, there are two possible ways to integrate an annex: using a simple path or a source path and a destination path. **Both paths need to be relative to `docs_dir`, though**.\n\nSet at least one annex to use this plugin. If you don't have any annex don't add this plugin to the mkdocs plugins list in config file mkdocs.yml\n\n- `annexes` - A list of all the annexes documents. The path from `docs_dir` to an annex file or directory associated to it's title. Each file in a directory will integrated in subsection of the same document with a heading 2 containing the relative path of the file from the given directory.\n- `temp_dir` - The temp directory used to generate markdown file for each annex before rendering to HTML. Only set this option if you already have a temp_annexes folder in the root directory (same as mkdocs.yml), which, you should not normally.\n- `enabled_if_env` - Setting this option will enable the build only if there is an environment variable set to 1. Integrations of PDF can slow down build process and it's pretty useful to be fast when doing modification to mkdocs files when doing mkdocs serve.\n\n## Usage\n\nUsing the command `mkdocs build` or `mkdocs serve` will trigger the plugin if it as been set correctly in config file.\n\nThis plugin is intended to be used with `mkdocs-with-pdf` plugin but can be used as it is.\n\n## Support\n\nThis plugin currently support two type of files :\n\n- **PDF files**: The plugin will convert each page of the PDF into images to be integrated on a page\n\n- **Code files**: The plugin will put the content of the code file into a codeblock to be integrated on a page\n\nCurrently supported code files are :\n - CSharp (.cs)\n - CSS (.css)\n - Dart (.dart)\n - HTML (.html)\n - Javascript (.js)\n - JSON (.json)\n - PHP (.php)\n - Python (.py)\n\n## License\n\nThis project is under MIT license see: `license` file for more detail.\n\n## See Also\n\n- [gitlab repo](http://www.gitlab.org/cfpt-mkdocs-plugins/mkdocs-annexes-integration/)\n- [mkdocs website](http://www.mkdocs.org/)\n- [mkdocs with-pdf plugin](https://github.com/orzih/mkdocs-with-pdf)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin transforming annexes files into images or code blocks to be integrated in markdown pages",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://gitlab.com/cfpt-mkdocs-plugins/mkdocs-annexes-integration"
},
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cef286bc70e67b2ceb714e973a236d977331698733ec1d2589ec8a8d05b32edb",
"md5": "bc7fcb25f7b28f26c54ecee8d99af99d",
"sha256": "34f084cbe68b2d398fc1d15471aea728c00a8145d3306cdc6c02305d977011ad"
},
"downloads": -1,
"filename": "mkdocs_annexes_integration-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc7fcb25f7b28f26c54ecee8d99af99d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6465,
"upload_time": "2023-06-07T13:16:11",
"upload_time_iso_8601": "2023-06-07T13:16:11.432115Z",
"url": "https://files.pythonhosted.org/packages/ce/f2/86bc70e67b2ceb714e973a236d977331698733ec1d2589ec8a8d05b32edb/mkdocs_annexes_integration-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ae84810e995b2cf3950030fef9333e30d7cce21a88ba6725b6de77e84c3e67d7",
"md5": "1f6984c311930d3a971d00f3d3002baa",
"sha256": "6d31309c532881b0cc242bbb3f49a1f8ca49b682a6378cd8e336fdf685d939f8"
},
"downloads": -1,
"filename": "mkdocs-annexes-integration-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "1f6984c311930d3a971d00f3d3002baa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7267,
"upload_time": "2023-06-07T13:16:13",
"upload_time_iso_8601": "2023-06-07T13:16:13.335462Z",
"url": "https://files.pythonhosted.org/packages/ae/84/810e995b2cf3950030fef9333e30d7cce21a88ba6725b6de77e84c3e67d7/mkdocs-annexes-integration-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-07 13:16:13",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cfpt-mkdocs-plugins",
"gitlab_project": "mkdocs-annexes-integration",
"lcname": "mkdocs-annexes-integration"
}
JSON