# mkdocs-bioinformatic-izsam-theme
This is an MkDocs theme designed to layout the documentation provided by Bioinformatic Unit of the Istituto Zooprofilattico Sperimentale dell'Abruzzo e del Molise "G. Caporale".
#### Important!
The theme is intended to work with the plugin **mkdocs-izsam-search** [https://pypi.org/project/mkdocs-izsam-search/](https://pypi.org/project/mkdocs-izsam-search/)
```bash
pip install mkdocs-izsam-search
```
## Theme customization
The theme allows you to customize platform title and footer contents by using your mdkdocs configuration file `mkdocs.yml`.
```yaml
extra:
platform_title: Piattaforma GenPat, Wiki
language: it
useful_links:
link_1:
label: CRN Sequenze Genomiche
url: https://www.izs.it/IZS/Eccellenza/Centri_nazionali/CRN_-_Sequenze_Genomiche
link_2:
label: IZSAM "G. Caporale"
url: https://www.izs.it
support:
support_1:
label: bioinformatica@izs.it
url: mailto:bioinformatica@izs.it
support_2:
label: +39 0861 3321
url: tel:+3908613321
tools:
tool_1:
icon: iconic-print
label: Versione PDF
target: _blank
url: https://genpat.izs.it/genpat_wiki/en/pdf/genpat_platform_wiki.pdf
copyright: IZSAM "G. Caporale"
```
## Multi language support
The theme supports a localization system written in javascript. At the moment it supports Italian and English but it is possible to add new languages.
### Add a language
1. Create a new language file in `js/i18n` folder by using `en.js` or `it.js` as template and translate values.
2. List it in `js/languages-builder.js`
3. Pack language files in `languages.js`
#### Pack language files
To pack files we use [**packjs**](https://www.npmjs.com/package/packjs) npm library:
```bash
npm install --save-dev packjs
```
Then from `js` folder:
```bash
packjs i18n/languages-builder.js languages.js
```
The code will loop through the `wiki.languages` object keys and for each key, it will add an option to the language switcher. By selecting an available language, the code will redirect to the language subfolder.
The theme is designed to handle different builds for each language. Specifically, we will have the documentation in Italian hosted under `https://mywiki.eu/it`, the documentation in English under `https://mywiki.eu/en`, and so on.
> **Please note:** If you have a single language site, just remove the languages you don't need from `js/languages.js`. If you want to modify the behavior of the language switcher, you can override the `js/locales.js` file.
### Language definition
Each build relies on `config.extra.language` parameter to define the wiki language (the default is `en`), on `base.html` we set the html `lang` attribute and a global javascript constant `config_lang` with that value:
```html
<html lang="{{ config.extra.language|default('en') }}">
```
```javascript
const config_lang = "{{ config.extra.language|default('en') }}";
```
The `config.extra.language` variable is used also to set **search functionalities**. There are some limitations on the values it can assume. Allowed languages are: `ar`, `da`, `de`, `du`, `es`, `fi`, `fr`, `hi`, `hu`, `it`, `ja`, `jp`, `nl`, `no`, `pt`, `ro`, `ru`, `sv`, `ta`, `th`, `tr`, `vi`, `zh`. If you want to use a different language, you should not to use **mkdocs-izsam-search** plugin and customize the `base.html` file removing all the code related to it.
```html
{% if config.extra.language and not 'en' in config.extra.language %}
<script src="{{ 'js/lunr-languages/lunr.stemmer.support.js'|url }}"></script>
<script src="{{ 'js/lunr-languages/lunr.multi.js'|url }}"></script>
{% set js_path = 'js/lunr-languages/lunr.' ~ config.extra.language ~ '.js' %}
<script src="{{ js_path|url }}"></script>
{% endif %}
```
## Theme features
#### Use image caption
If you need to use a caption for images, you can use the markdown image title sintax.
``
> A function in `theme.js` loops all images and if a title exists will append a `figcaption` tag after the image.
#### Use icons inline
To use icons inline inside the contents, please add the alt attribute `inline-icon`:
```
```
> Images will have inherent size and displayed inline.
#### Use diagram as images (no plantuml)
To use diagram inside the contents as images, please add the alt attribute `diagram` to avoid box shadow.
```
```
## Credits
For the icons, we are using the free [Iconic](https://iconic.app/) package, converted to a font with the [IcoMoon app](https://icomoon.io/app/#/select).
# Change log
## [1.0.1] - 2025-01-30
### Bug fix and cleaning
Fixed formatting problem with last update date on footer, reoved unused code
## [1.0.0] - 2025-01-28
### Refactoring
Theme code refactoring in order to have greater modularity for overrides, better localization management, and improved flexibility with the use of extra mkdocs configuration variables.
## [0.2.8] - 2024-09-17
### Added css style in order to manage Mermaid diagrams
Added support in general theme css rules for Mermaid diagrams generated by mkdocs-izsam-mermaid-to-images plugin
## [0.2.7] - 2024-09-16
### Added home link for header logo
## [0.2.6] - 2024-09-10
### Fixed style for indented list
## [0.2.5] - 2024-06-17
### Fixed package problem related to build process
## [0.2.4] - 2024-06-17
### New style for table
## [0.2.3] - 2023-12-1
### Added new logo and canged accent color
## [0.2.1] - 2023-08-29
### Small fix related to 0.2 release
- Edited base.html
## [0.2] - 2023-08-29
### Refactoring and bug fix for search
Change in multilingual handling for search in order to resolve issues related to searching for words containing the underscore character (`_`).
- Edited base.html
- Edited js/search.js
## [0.1.9.3] - 2023-05-15
### Ux improvement for main menu in mobile view
- Edited theme.css
- Edited base.html
## [0.1.9.2] - 2023-03-28
### Bug fix for ordered list
- Edited theme.css
## [0.1.9.1] - 2022-12-09
### Ux improvement for main menu in mobile view
- Edited theme.css
## [0.1.9] - 2022-10-24
### Small fix on Ux improvement for main menu in mobile view
- Edited theme.css and base.html
## [0.1.8] - 2022-10-24
### Ux improvement for main menu in mobile view
- Edited theme.css and base.html
## [0.1.7] - 2022-05-12
### Debug and refactoring for theme.js
- Edited theme.js
## [0.1.6] - 2022-05-12
### Fix for image caption function
- Edited theme.css and theme.js
## [0.1.5] - 2022-05-12
### Added support for image caption
- Edited theme.css and theme.js
### Readme improvements
- Edited README.md
## [0.1.4] - 2022-05-2
### CSS: added rule for html video tag
- Edited theme.css
## [0.1.3] - 2022-04-27
### Html base template: changed next and previous buttons in order to integrate parent title
- Edited base.html
## [0.1.2] - 2022-03-18
### Layout improvement.
- Edited theme.css
## [0.1.1] - 2022-01-25
### Layout improvement.
- Edited theme.css
## [0.1.0] - 2022-01-25
### Layout improvement.
- Edited theme.css
## [0.0.9] - 2022-01-25
### Layout changes: form fields and buttons aspect.
- Edited theme.css
## [0.0.8] - 2021-11-24
### Layout improvement.
- Edited theme.css
## [0.0.7] - 2021-11-15
### Project description.
- Edited README.md
## [0.0.6] - 2021-11-15
### Theme localization, integration of a footer.css, ui emprovement.
- Added theme localization for search.html file.
- Added theme localization for 404.html file.
- Added a footer.css file.
- Small changes in the main theme.css style for left menu.
## [0.0.5] - 2021-11-12
### Theme localization
- The theme now support it and en localization and it can be extended with other langauges.
## [0.0.4] - 2021-11-12
### Added support for other languages besides `en` to make theme working with mkdocs-izsam-search plugin
- The theme now support languages present in `js/lunr-languages` and can be defined in `theme.locale` of the `.yml` configuration file. Multilanguage is not supported yet.
## [0.0.2] and [0.0.3] - 2021-11-11
### Debug on setup
- Fixed bugs for the mkdocs entry point in `setup.py`
## [0.0.1] - 2021-11-11
### First release
- Made stuff necessary to package a theme
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-bionformatic-izsam-theme",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "MkDocs, Theme, Software documentation",
"author": "Alessandro De Luca",
"author_email": "al.deluca@izs.it",
"download_url": "https://files.pythonhosted.org/packages/be/a1/c92fa1b94b114af13a65c5a3f3d2a20effc05c4cb778d2b55b1b0502106f/mkdocs_bionformatic_izsam_theme-1.0.1.tar.gz",
"platform": null,
"description": "# mkdocs-bioinformatic-izsam-theme\n\nThis is an MkDocs theme designed to layout the documentation provided by Bioinformatic Unit of the Istituto Zooprofilattico Sperimentale dell'Abruzzo e del Molise \"G. Caporale\".\n\n#### Important!\n\nThe theme is intended to work with the plugin **mkdocs-izsam-search** [https://pypi.org/project/mkdocs-izsam-search/](https://pypi.org/project/mkdocs-izsam-search/)\n\n```bash\npip install mkdocs-izsam-search\n```\n\n## Theme customization\n\nThe theme allows you to customize platform title and footer contents by using your mdkdocs configuration file `mkdocs.yml`.\n\n```yaml\nextra:\n platform_title: Piattaforma GenPat, Wiki\n language: it\n useful_links:\n link_1:\n label: CRN Sequenze Genomiche\n url: https://www.izs.it/IZS/Eccellenza/Centri_nazionali/CRN_-_Sequenze_Genomiche\n link_2:\n label: IZSAM \"G. Caporale\"\n url: https://www.izs.it\n support:\n support_1:\n label: bioinformatica@izs.it\n url: mailto:bioinformatica@izs.it\n support_2:\n label: +39 0861 3321\n url: tel:+3908613321\n tools:\n tool_1:\n icon: iconic-print\n label: Versione PDF\n target: _blank\n url: https://genpat.izs.it/genpat_wiki/en/pdf/genpat_platform_wiki.pdf\n copyright: IZSAM \"G. Caporale\"\n```\n\n## Multi language support\n\nThe theme supports a localization system written in javascript. At the moment it supports Italian and English but it is possible to add new languages.\n\n### Add a language\n\n1. Create a new language file in `js/i18n` folder by using `en.js` or `it.js` as template and translate values.\n2. List it in `js/languages-builder.js`\n3. Pack language files in `languages.js` \n\n#### Pack language files\n\nTo pack files we use [**packjs**](https://www.npmjs.com/package/packjs) npm library:\n\n```bash\nnpm install --save-dev packjs\n```\n\nThen from `js` folder:\n\n```bash\n packjs i18n/languages-builder.js languages.js\n```\n\nThe code will loop through the `wiki.languages` object keys and for each key, it will add an option to the language switcher. By selecting an available language, the code will redirect to the language subfolder.\n\nThe theme is designed to handle different builds for each language. Specifically, we will have the documentation in Italian hosted under `https://mywiki.eu/it`, the documentation in English under `https://mywiki.eu/en`, and so on.\n\n> **Please note:** If you have a single language site, just remove the languages you don't need from `js/languages.js`. If you want to modify the behavior of the language switcher, you can override the `js/locales.js` file.\n\n### Language definition\n\nEach build relies on `config.extra.language` parameter to define the wiki language (the default is `en`), on `base.html` we set the html `lang` attribute and a global javascript constant `config_lang` with that value:\n\n```html\n<html lang=\"{{ config.extra.language|default('en') }}\">\n```\n\n```javascript\nconst config_lang = \"{{ config.extra.language|default('en') }}\";\n```\n\nThe `config.extra.language` variable is used also to set **search functionalities**. There are some limitations on the values it can assume. Allowed languages are: `ar`, `da`, `de`, `du`, `es`, `fi`, `fr`, `hi`, `hu`, `it`, `ja`, `jp`, `nl`, `no`, `pt`, `ro`, `ru`, `sv`, `ta`, `th`, `tr`, `vi`, `zh`. If you want to use a different language, you should not to use **mkdocs-izsam-search** plugin and customize the `base.html` file removing all the code related to it.\n\n```html\n{% if config.extra.language and not 'en' in config.extra.language %}\n <script src=\"{{ 'js/lunr-languages/lunr.stemmer.support.js'|url }}\"></script>\n <script src=\"{{ 'js/lunr-languages/lunr.multi.js'|url }}\"></script>\n {% set js_path = 'js/lunr-languages/lunr.' ~ config.extra.language ~ '.js' %}\n <script src=\"{{ js_path|url }}\"></script>\n{% endif %}\n```\n\n## Theme features\n\n#### Use image caption\n\nIf you need to use a caption for images, you can use the markdown image title sintax.\n\n`![](image.png \"image title\")`\n\n> A function in `theme.js` loops all images and if a title exists will append a `figcaption` tag after the image.\n\n#### Use icons inline\n\nTo use icons inline inside the contents, please add the alt attribute `inline-icon`:\n\n```\n\n```\n\n> Images will have inherent size and displayed inline.\n\n#### Use diagram as images (no plantuml)\n\nTo use diagram inside the contents as images, please add the alt attribute `diagram` to avoid box shadow.\n\n```\n\n```\n\n## Credits\n\nFor the icons, we are using the free [Iconic](https://iconic.app/) package, converted to a font with the [IcoMoon app](https://icomoon.io/app/#/select).\n\n# Change log\n\n## [1.0.1] - 2025-01-30\n\n### Bug fix and cleaning\nFixed formatting problem with last update date on footer, reoved unused code\n\n## [1.0.0] - 2025-01-28\n\n### Refactoring\nTheme code refactoring in order to have greater modularity for overrides, better localization management, and improved flexibility with the use of extra mkdocs configuration variables.\n\n## [0.2.8] - 2024-09-17\n\n### Added css style in order to manage Mermaid diagrams\nAdded support in general theme css rules for Mermaid diagrams generated by mkdocs-izsam-mermaid-to-images plugin\n\n## [0.2.7] - 2024-09-16\n\n### Added home link for header logo\n\n## [0.2.6] - 2024-09-10\n\n### Fixed style for indented list\n\n## [0.2.5] - 2024-06-17\n\n### Fixed package problem related to build process\n\n## [0.2.4] - 2024-06-17\n\n### New style for table\n\n## [0.2.3] - 2023-12-1\n\n### Added new logo and canged accent color\n\n## [0.2.1] - 2023-08-29\n\n### Small fix related to 0.2 release\n- Edited base.html\n\n## [0.2] - 2023-08-29\n\n### Refactoring and bug fix for search\nChange in multilingual handling for search in order to resolve issues related to searching for words containing the underscore character (`_`).\n- Edited base.html\n- Edited js/search.js\n\n## [0.1.9.3] - 2023-05-15\n\n### Ux improvement for main menu in mobile view\n- Edited theme.css\n- Edited base.html\n\n## [0.1.9.2] - 2023-03-28\n\n### Bug fix for ordered list\n- Edited theme.css\n\n## [0.1.9.1] - 2022-12-09\n\n### Ux improvement for main menu in mobile view\n- Edited theme.css\n\n## [0.1.9] - 2022-10-24\n\n### Small fix on Ux improvement for main menu in mobile view\n- Edited theme.css and base.html\n\n## [0.1.8] - 2022-10-24\n\n### Ux improvement for main menu in mobile view\n- Edited theme.css and base.html\n\n## [0.1.7] - 2022-05-12\n\n### Debug and refactoring for theme.js\n- Edited theme.js\n\n## [0.1.6] - 2022-05-12\n\n### Fix for image caption function\n- Edited theme.css and theme.js\n\n## [0.1.5] - 2022-05-12\n\n### Added support for image caption\n- Edited theme.css and theme.js\n\n### Readme improvements\n- Edited README.md\n\n## [0.1.4] - 2022-05-2\n\n### CSS: added rule for html video tag\n- Edited theme.css\n\n## [0.1.3] - 2022-04-27\n\n### Html base template: changed next and previous buttons in order to integrate parent title\n- Edited base.html\n\n## [0.1.2] - 2022-03-18\n\n### Layout improvement.\n- Edited theme.css\n\n## [0.1.1] - 2022-01-25\n\n### Layout improvement.\n- Edited theme.css\n\n## [0.1.0] - 2022-01-25\n\n### Layout improvement.\n- Edited theme.css\n\n## [0.0.9] - 2022-01-25\n\n### Layout changes: form fields and buttons aspect.\n- Edited theme.css\n\n## [0.0.8] - 2021-11-24\n\n### Layout improvement.\n- Edited theme.css\n\n## [0.0.7] - 2021-11-15\n\n### Project description.\n- Edited README.md\n\n## [0.0.6] - 2021-11-15\n\n### Theme localization, integration of a footer.css, ui emprovement.\n- Added theme localization for search.html file.\n- Added theme localization for 404.html file.\n- Added a footer.css file.\n- Small changes in the main theme.css style for left menu.\n\n## [0.0.5] - 2021-11-12\n\n### Theme localization\n- The theme now support it and en localization and it can be extended with other langauges.\n\n## [0.0.4] - 2021-11-12\n\n### Added support for other languages besides `en` to make theme working with mkdocs-izsam-search plugin\n- The theme now support languages present in `js/lunr-languages` and can be defined in `theme.locale` of the `.yml` configuration file. Multilanguage is not supported yet.\n\n## [0.0.2] and [0.0.3] - 2021-11-11\n\n### Debug on setup\n- Fixed bugs for the mkdocs entry point in `setup.py` \n\n## [0.0.1] - 2021-11-11\n\n### First release\n- Made stuff necessary to package a theme\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs theme designed for Bioiformatic Unit of the Istituto Zooprofilattico dell' Abruzzo e del Molise G. Caporale",
"version": "1.0.1",
"project_urls": null,
"split_keywords": [
"mkdocs",
" theme",
" software documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45f3b72d4dff76679435554d5153af5333cd69e36e3475012d0ff2f792b79dc8",
"md5": "3585166f6eafa29693f70f1ead1c3806",
"sha256": "e7eb0ac1688d72810323daa187b2ecf7ce37bb50851a590afdc0181ac37b1295"
},
"downloads": -1,
"filename": "mkdocs_bionformatic_izsam_theme-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3585166f6eafa29693f70f1ead1c3806",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1081924,
"upload_time": "2025-01-30T11:42:15",
"upload_time_iso_8601": "2025-01-30T11:42:15.116882Z",
"url": "https://files.pythonhosted.org/packages/45/f3/b72d4dff76679435554d5153af5333cd69e36e3475012d0ff2f792b79dc8/mkdocs_bionformatic_izsam_theme-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bea1c92fa1b94b114af13a65c5a3f3d2a20effc05c4cb778d2b55b1b0502106f",
"md5": "d455da0d7e806761dd293b0df3d13c40",
"sha256": "425257a632322fd67b0107077327c0cd6bb49df5dca6bc88fc4e9693f9668688"
},
"downloads": -1,
"filename": "mkdocs_bionformatic_izsam_theme-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d455da0d7e806761dd293b0df3d13c40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1037652,
"upload_time": "2025-01-30T11:42:17",
"upload_time_iso_8601": "2025-01-30T11:42:17.404083Z",
"url": "https://files.pythonhosted.org/packages/be/a1/c92fa1b94b114af13a65c5a3f3d2a20effc05c4cb778d2b55b1b0502106f/mkdocs_bionformatic_izsam_theme-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-30 11:42:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mkdocs-bionformatic-izsam-theme"
}
JSON