# mkdocs-annexes-integration
This is a plugin that transforms annex files into images 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 annex:
src: ../src/path/to/an/annex/file1.py
dest: dest/path/to/an/annex/file1.py
# others annexes...
temp_dir: "folder_name" # Optional --> Default : temp_annexes
enabled_if_env: ENABLE_PDF_EXPORT # Optional
placeholders_when_disabled: true # Optional --> Default : false
```
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 associated to it's title
- `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.
- `placeholders_when_disabled` - This option will generate an mock file at the place of the integrated file to prevent warning from unreferenced link to the page by other pages. It is intended to be used with `enabled_if_env`.
## 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.
It is also strongly recommended to use it with `mkdocs-material` plugin. Using this plugin without `mkdocs-material` may result in unecessary page break between annex title and annex images.
## Support
This plugin currently support PDF files :
- **PDF files**: The plugin will convert each page of the PDF into images to be integrated on a page
## 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)
- [mkdocs material plugin](https://github.com/squidfunk/mkdocs-material)
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/cfpt-mkdocs-plugins/mkdocs-annexes-integration",
"name": "mkdocs-annexes-integration",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs",
"author": "Thibaud Briard",
"author_email": "thibaud.brrd@eduge.ch",
"download_url": "https://files.pythonhosted.org/packages/61/92/5aa1ca72566f11c3b6469e916cd9aeff09dba46fa3f12567f46cbf60334e/mkdocs-annexes-integration-0.1.7.tar.gz",
"platform": null,
"description": "# mkdocs-annexes-integration\n\nThis is a plugin that transforms annex files into images 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 annex:\n src: ../src/path/to/an/annex/file1.py\n dest: dest/path/to/an/annex/file1.py\n # others annexes...\n temp_dir: \"folder_name\" # Optional --> Default : temp_annexes\n enabled_if_env: ENABLE_PDF_EXPORT # Optional\n placeholders_when_disabled: true # Optional --> Default : false\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 associated to it's title\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- `placeholders_when_disabled` - This option will generate an mock file at the place of the integrated file to prevent warning from unreferenced link to the page by other pages. It is intended to be used with `enabled_if_env`.\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\nIt is also strongly recommended to use it with `mkdocs-material` plugin. Using this plugin without `mkdocs-material` may result in unecessary page break between annex title and annex images.\n\n## Support\n\nThis plugin currently support PDF files :\n\n- **PDF files**: The plugin will convert each page of the PDF into images to be integrated on a page\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- [mkdocs material plugin](https://github.com/squidfunk/mkdocs-material)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin transforming annexes files into images to be integrated in markdown pages",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://gitlab.com/cfpt-mkdocs-plugins/mkdocs-annexes-integration"
},
"split_keywords": [
"mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6b3fc2f513364a8ec0527407e2f4be15fd79d43f62a8bdaac99d4e92a4156852",
"md5": "a852520ea39400f928f318e3063c0751",
"sha256": "a05eba6428a05ba890e15325c006f5778cd04cda381da9a4d5967720ce906678"
},
"downloads": -1,
"filename": "mkdocs_annexes_integration-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a852520ea39400f928f318e3063c0751",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6322,
"upload_time": "2024-05-08T15:16:54",
"upload_time_iso_8601": "2024-05-08T15:16:54.219657Z",
"url": "https://files.pythonhosted.org/packages/6b/3f/c2f513364a8ec0527407e2f4be15fd79d43f62a8bdaac99d4e92a4156852/mkdocs_annexes_integration-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61925aa1ca72566f11c3b6469e916cd9aeff09dba46fa3f12567f46cbf60334e",
"md5": "8a375cebc25bd92d71a749dbc30bcc13",
"sha256": "ecf541f754825a9d2f76b896be96324e102913d1e507d92742ab88e108bd1517"
},
"downloads": -1,
"filename": "mkdocs-annexes-integration-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "8a375cebc25bd92d71a749dbc30bcc13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7173,
"upload_time": "2024-05-08T15:16:56",
"upload_time_iso_8601": "2024-05-08T15:16:56.103807Z",
"url": "https://files.pythonhosted.org/packages/61/92/5aa1ca72566f11c3b6469e916cd9aeff09dba46fa3f12567f46cbf60334e/mkdocs-annexes-integration-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-08 15:16:56",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "cfpt-mkdocs-plugins",
"gitlab_project": "mkdocs-annexes-integration",
"lcname": "mkdocs-annexes-integration"
}
JSON