Translation example for mkdocs_translatescript Release {{ release }}.
Translation example for mkdocs_translatescript Release 0.9.
Translation example for mkdocs_translatescript Release {{ release }}.
Note
This is an example project, see project README.md for most recent instructions.
The mkdocs_translate script is open-source using The MIT License (MIT).
"},{"location":"development/","title":"Development","text":""},{"location":"development/#local-development","title":"Local Development","text":"To build and test locally:
Clone:
git clone https://github.com/jodygarnett/translate.git translate\nInstall requirements:
cd translate\npip3 install -r mkdocs_translate/requirements.txt\nInstall locally:
pip3 install -e .\nRecommend troubleshooting a single file at a time:
mkdocs_translate migrate source/index.rst\nCompare the temporary files staged for pandoc conversion:
bbedit source/index.rst docs/index.md build/migrate/index.tmp.html build/migrate/index.tmp.md\nTo turn on logging during migrating a file:
mkdocs_translate --log=DEBUG migrate source/index.rst\nTo troubleshoot indexing when scanning a single document:
mkdocs_translate --log=DEBUG scan index --TEST source/index.rst\nThe index information is sent to standard out (rather than added to a anchor.txt file.
To troubleshoot downloads when scanning a single document:
mkdocs_translate --log=DEBUG scan download --TEST source/index.rst\nThe download information is sent to standard out (rather than a download.txt file.
The pandoc plugin settings are in two constants:
md_extensions_to =\n 'markdown+definition_lists+fenced_divs+backtick_code_blocks+fenced_code_attributes-simple_tables+pipe_tables'\nmd_extensions_from =\n 'markdown+definition_lists+fenced_divs+backtick_code_blocks+fenced_code_attributes+pipe_tables'\nThe pandoc extensions are chosen to align with mkdocs use of markdown extensions, or with post-processing:
markdown extension pandoc extension post processing tables pymdownx.keys pipe_tables post processing pymdownx.superfences backtick_code_blocks post processing admonition fenced_divs post processingLanguage translation depends on conversion to and from html. To troubleshoot just the markdown to html conversion:
mkdocs_translate internal_html docs/contributing/style-guide.md\nmkdocs_translate internal_markdown build/convert/contributing/style-guide.html\n\ndiff docs/contributing/style-guide.md build/convert/contributing/style-guide.md\nLangauge conversion uses text/htmlto avoid internationalization of content distributing markdown formatting.
Copyright \u00a9 2024 Jody Garnett
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"guide/","title":"Writing Guide","text":"Working with documentation, markdown formatting, and writing style guide.
Note
The mkdoc_translate script can adapt some markdown extensions for use with pandoc conversion, but not everything.
While it is fine to use the mkdoc_translate script for initial Content Migration, if you wish to continue using this tool for language translation you are advised to keep the following writing guidelines in mind.
Material for MkDocs
The writing guide is setup for use with the excellent Material for MkDocs.
This is a great project that was selected by the GeoNetwork community (primarily for the visual appeal). In practice it ends up being quite a nice way to \"keep up\" with advances in the mkdocs ecosystem without having to constantly research what is best.
"},{"location":"guide/markdown/","title":"Markdown","text":"These markdown conventions are carefully constructed for consistent representation of user interface elements, files, data and field input.
Markdown Directive strong gui label, menu selectionmonospace text input, item selection emphasis figure (caption) strong-emphasis application, command monospace-strong file Note
The above conventions are important for consistency and are required by the translation process.
As an example we do not wish to translate keyboard input, so these are represented as monospace text input.
"},{"location":"guide/markdown/#user-interface-components","title":"User interface components","text":"Use **strong**to name user interface components for interaction (press for buttons, click for link).
Preview:
Navigate to Data \u2192 Layers page, and press Add to create a new layer.
Markdown uses **strong**
Navigate to **Data > Layers** page,\nand press **Add** to create a new layer.\nRich structured text uses menuselectionand guilabeldirectives:
Navigate to **Data --> Layers** page,\nand press **Add** to create a new layer.\nUse item for user selected input, or item in a list or tree:
Preview:
Select Basemap layer.
Markdown uses monospace:
Select ``Basemap``layer.\nRich structured text uses monospace:
Select ``Basemap`` layer.\nUse monospace for user supplied text input:
Preview:
Use the Search field to enter: Ocean*
Markdown uses monospace:
Use the **Search** field enter: ``Ocean*``\nRich structured text uses kbd directive:
Use the **Search** field to enter: ``Ocean*``\nUse key directive for keyboard keys.
Preview:
Press Control-sto search.
Markdown uses mkdocs-material keys formatting:
Press ++control+s++ to search.\nRich structured text:
Press ``Control-s``to search.\nUse definition list to document data entry. The field names use strong as they name a user interface element. Field values to input uses monspace as user input to type in.
Preview:
To login as the GeoServer administrator using the default password:
User:admin
geoserver
Unchecked
Press Login.
Markdown: definition lists
1. To login as the GeoServer administrator using the default password:\n\n **User**\n\n : ``admin``\n\n **Password**\n\n : ``geoserver``\n\n **Remember me**\n\n : Unchecked\n\n Press **Login**.\nRich structured text: list-table
#. To login as the GeoServer administrator using the default password:\n\n .. list-table::\n :widths: 30 70\n :width: 100%\n :stub-columns: 1\n\n * - User:\n - ``admin`` * - Password:\n - ``geoserver`` * - Remember me\n - Unchecked\n\n Press **Login**.\nUse bold with italics for proper names of applications, commands, tools, and products.
Preview:
Launch pgAdmin and connect to the tutorial database.
Markdown:
Launch ***pgAdmin*** and connect to the ``tutorial``database.\nRich structured text uses command directive:
Launch ***pgAdmin*** and connect to the ``tutorial`` database.\nUse bold with monospace for files and folders:
Preview
See configuration file WEB-INF/config-security/config-security-ldap.xml for details
Markdown:
See configuration file\n**`WEB-INF/config-security/config-security-ldap.xml`**\nfor details\nRich structured text:
See configuration\nfile **`WEB-INF/config-security/config-security-ldap.xml`**\nfor details\nReference to other section of the document (some care is required to reference a specific heading):
Authors have access to translation for initial draft.
Markdown use of relative links and anchor:
Authors have access to [translation](../translate/language#translate) for initial draft.\nreStructuredText use of ref directive:
Authors have access to `translation <../translate/language.rst#translate>`_ for initial draft.\nSample file included in the documentation:
Download schema example.txt.
Markdown relative link, with text following bold with monospacefile convention above:
Download text [**`example.txt`**](files/example.txt).\nYou may also experiment with mkdocs attr_list to supply a filename:
Download text [**`example.txt`**](files/example.txt) {:download=\"example.txt\"} .\nreStructured text uses downlaod directive:
Download text `example.txt <files/example.txt>`__.\nTo include sample file from outside of the documentation tree:
Open-source LICENSE.md
Note
This functionality is not supported by Material for mkdocs (or any plugin I could find). It is accomplished using the download.py hook described in setup.
To use download.py hook, create a download folder to hold staged files
Markdown refers to this folder using a relative link (like normal):
Open-source [**`LICENSE.md`**](download/LICENSE.md)\nCreate download/download.txt with list of files to stage during mkdocs build process:
# files list for mkdocs hook staging download content\n\nLICENSE.md=../../../../LICENSE.md\nreStructuredText uses download directive with relative path (you may starting leading / to indicate the root of the documentation source folder):
Open-source `LICENSE.md <download/LICENSE.md>`__\nMaterial for mkDocs has extensive icon support, for many user interface elements we can directly make use of the appropriate icon in Markdown:
1. Press the *Validate :fontawesome-solid-check:* button at the top of the page.\nCustom icons:
Empower everyone with open source geospatial
Material for MkDocs provides support for custom icons:
:osgeo-logo: Empower everyone with open source geospatial\nAdd images to overrides/.icons/ (yes it is a hidden folder):
overrides/\n- .icons/\n - osgeo/\n logo.svg\nreStructuredText does not offer custom icons, the closest is the use of substitutions to \"inline\" and image.
.. |osgeo_mark| image:: img/osgeo_mark.svg\n :width: 20\n :height: 20\n\n|osgeo_mark| Empower everyone with open source geospatial\nWarning
The mkdocs_translate and pandoc combo is unable to convert inline images at this time.
[WARNING] Reference not found for 'Key \"osgeo_mark\"' at build/migrate/guide/markdown.tmp.prep.rst_chunk line 5 column 13\nFigures are used frequently to allow a caption to describe screen shots and diagrams.
Free and Open Source Software for Geospatial
Markdown handles figures are handled by convention adding emphasized text after each image.
\n*Free and Open Source Software for Geospatial*\nNote
The convention above depends on CSS rules in overrides/assets/stylesheets/extra.css to provide a consistent presentation:
img + em, .browser-border + em, .browser-mockup + em {\n display: block;\n text-align: left;\n font-size: 0.7rem;\n font-style: normal;\n}\nNote
The official Material for MkDocs answer for images with captions is to use md_in_html extension:
<figure markdown=\"span\">\n { scale=\"25%\" }\n <figcaption>Free and Open Source Software for Geospatial</figcaption>\n</figure>\nreStructuredText has a figure directive:
.. code-block:: raw_markdown\n\n \n *Free and Open Source Software for Geospatial*\nImage content:
Markdown provides inline image syntax.
\nUse of mkdocs att_list can be used to adjust scale:
{ scale=\"25%\" }\nreStructuredText has an image directive:
.. image:: img/foss4g.svg\n :scale: 25%\nMaterial for MkDocs :squidfunkdata tables <reference/data-tables/> use pipe-tables approach (supported by both mkdocs and pandoc):
Leading ` | tailing ```:
| First Header | Second Header | Third Header |\n|--------------|---------------|--------------|\n| Content Cell | Content Cell | Content Cell |\n| Content Cell | Content Cell | Content Cell |\nColumn alignment using :
| First Header | Second Header | Third Header |\n|:-------------|:-------------:|-------------:|\n| Left | Center | Right |\n| Left | Center | Right |\nUse of mkdocs-include-plugin provides ability to inline content. Example project uses following mkdocs.yml setup:
plugins:\n - include-markdown:\n preserve_includer_indent: true\n dedent: true\n comments: false\nThe official Material for mkdocs guidance is to use snippets however this did not offer the ability to include code examples and configuration from outside the document tree.
Reference
Inlining a snippet from another file is helpful for material such as disclaimers or statements which are repeated in text.
Empower everyone with open source geospatial
Here is a snippet to include markdown files inline, requires opening tag {% and closing tag %}:
{/\n include-markdown 'files/vision_statement.txt'\n/}\nNote
Placeholders {/and /}used to indicate location of {%and %}in above code example.
Writers can use include-markdown with a glob pattern to inline many files, and an option to adjusting header level. Together these two features can be used break up longer pages into more manageable size.
This takes the place of the sphinx-build include directive:
.. include:: files/vision_statement.txt\nNote
You may wish to use the txt extension for included content. If you wish to use md extension you can adjust mkdocs.yml exclude or not not_in_nav to address warnings.
plugins:\n - exclude:\n glob:\n - '**/files/*.md'\nIncluding configuration and code examples:
<CharacterString>da165110-88fd-11da-a88f-000d939bc5d8</CharacterString>\nUse includeto include normal files, with optional use of start and end markers to capture a snippet, and dedent for appearance.
In this case we are including content into an xml code block to provide syntax highlighting, requires opening tag {% and closing tag %} within the code block:
``` xml\n{/\n include 'files/record.xml'\n dedent=\"true\"\n start=\"<!--start-->\"\n end=\"<!--end-->\"\n/}\n```\nNote
Placeholders {/and /}used to indicate location of {%and %}in above code example.
This takes the place of the sphinx-build literal-include directive:
.. literalinclude:: files/record.xml\n :language: xml\n :start-after: <!--start-->\n :end-before: <!--end-->\n :dedent:\nWriting style guide to help creating consistent documentation.
This style guide is useful as a reference when reviewing pull-requests for documentation.
Reference
Documentation should be concise and not just a brain dump. Reference material should contain short pages and be easy to refer to without having to scroll through a large volume of text. Tutorials can be longer, depending on scope. If the point of the document is to share your thoughts and insights, it belongs in a blog post. This documentation is a manual, not a wiki.
"},{"location":"guide/style/#avoid-marketing","title":"Avoid marketing","text":"If the point of the document is to showcase a new feature it does not belong in the documentation. Write an article or a blog post about it. If it is necessary to point out a technical benefit of a feature then do so from a technical standpoint.
Bad
Sub-Portals are a great way to provide a team with their own catalogue!
Good
Sub-Portals define a distinct catalogue for use.
"},{"location":"guide/style/#be-professional","title":"Be professional","text":"Avoid the use of slang or other \"colorful\" language. The point of a technical document is to be informative, not to keep the reader amused. Avoiding slang helps keep the document accessible to as large an audience as possible.
Bad
Good
When providing step-by-step instructions, number steps and use direct commands or requests. Avoid the use of \"we\" and \"let's\".
Bad
Now let's select a record by ...
Good
Reference
Each word in the page name should be capitalized except for articles (such as \"the\", \"a\", \"an\") and conjunctions (such as \"and\", \"but\", \"or\"). A page name should never start with an article.
Bad
Adding a wms or wfs service
Good
Adding a WMS or WFS service
Bad
The Harvester Tutorial
Good
Harvester Tutorial
"},{"location":"guide/style/#capitalization-of-section-names","title":"Capitalization of section names","text":"Do not capitalize second and subsequent words unless the title is almost always capitalized in English (like proper names). Thus, capitalize John Wayne and Art Nouveau, but not Video Games.
Bad
Creating a New Record
Good
Creating a new record
"},{"location":"guide/style/#verb-usage","title":"Verb usage","text":"It is recommended that the gerund (the -ing form in English) be used unless there is a more common noun form. For example, an article on swimming is better than one on swim.
Bad
Create a new datastore
Good
Creating a new datastore
"},{"location":"guide/style/#avoid-plurals","title":"Avoid plurals","text":"Create page titles that are in the singular. Exceptions to this are nouns that are always plural (scissors, trousers), a small class that requires a plural (polar coordinates, Bantu languages, The Beatles).
Bad
templates tutorial
Good
Template tutorial
"},{"location":"guide/style/#formatting","title":"Formatting","text":""},{"location":"guide/style/#code-and-command-line","title":"Code and command line","text":"Any code or command line snippets should be formatted as code:
{\n \"code\": \"This is a code block.\"\n}\nWhen lines are longer than 80 characters, extend multiple lines in a format appropriate for the language in use. If possible, snippets should be functional when pasted directly into the appropriate target.
For example, XML make no distinction between a single space and multiple spaces, so the following snippets are fine:
<namespace:tagname attributename=\"attributevalue\" attribute2=\"attributevalue\"\n nextattribute=\"this is on another line\"/>\nFor shell scripts, new lines can be escaped with a backslash character ([]{.title-ref}).
mvn clean install \\\n -DskipTests\nBUILD SUCCESS\nIt is helpful to separate out input from output, so that the command can be easily copied as shown above.
"},{"location":"guide/download/LICENSE/","title":"The MIT License (MIT)","text":"Copyright \u00a9 2024 Jody Garnett
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"setup/","title":"Getting started","text":""},{"location":"setup/#install","title":"Installation","text":"A translate script is provided to facilitate working with pandoc and deepl translation services.
To install development version use:
pip install git+https://github.com/jodygarnett/translate.git\nInstall script requirements, and check it runs:
mkdocs_translate --help\nThis script requires pandoc be installed:
Ubuntu:
apt-get install pandoc\nmacOS:
brew install pandoc\nReference
A working example is provided to be adapted for your project.
Create requirements.txt with mkdocs plugins required.
mkdocs-material>=9.5.9\nmkdocs-include-markdown-plugin>=6.0.4\nmkdocs-exclude>=1.0.2\nmkdocs-macros-plugin>=1.0.4\nCreate mkdocs.yml, the navigation tree is initially empty.
# Project information\nsite_name: MkDocs Translate\nsite_description: Example sphinx-build documentation project for use with mkdocs_translate script.\n\nsite_dir: build/html\nsite_url: http://jodygarnett.github.io/translate\n\n# Repository\nrepo_name: translate\nrepo_url: https://github.com/jodygarnett/translate\nedit_uri: edit/main/example/docs\n\n# Copyright\ncopyright: Copyright © 2024 Open Source Geospatial Foundation\n\nextra_css:\n - assets/stylesheets/extra.css\n\n# Configuration\ntheme:\n name: material\n language: en\n custom_dir: overrides\n # logo: assets/images/geoserver_mark.png\n # favicon: assets/images/geoserver_mark.png\n icon:\n repo: fontawesome/brands/github\n palette:\n # Palette toggle for light mode\n - media: \"(prefers-color-scheme: light)\"\n scheme: default\n primary: blue\n toggle:\n icon: material/weather-night\n name: Switch to dark mode\n # Palette toggle for dark mode\n - media: \"(prefers-color-scheme: dark)\"\n scheme: slate\n toggle:\n icon: material/weather-sunny\n name: Switch to light mode\n features:\n - content.action.view\n - content.action.edit\n - content.code.copy\n - content.tabs.link\n - navigation.tracking\n - navigation.prune\n - navigation.indexes\n - toc.follow\n - navigation.top\n - navigation.footer\n - announce.dismiss\n\n# Plugins - install using: pip3 install -r requirements.txt\nplugins:\n - exclude:\n glob:\n - '**/download/download.txt'\n - include-markdown:\n preserve_includer_indent: true\n dedent: true\n comments: false\n - macros:\n render_by_default: false\n on_error_fail: true\n on_undefined: strict\n j2_block_start_string: '[[%'\n j2_block_end_string: '%]]'\n - search\n\n# Customizations\nhooks:\n - download.py\nextra:\n homepage: http://jodygarnett.github.io/translate\n social:\n - icon: fontawesome/brands/github\n link: ttps://github.com/jodygarnett/translate\n version: '1.0'\n release: '1.0.0'\n\n# Extensions\n# - These are carefully chosen to work with pandoc markdown support for whole document translation\nmarkdown_extensions:\n - admonition\n - attr_list\n - def_list\n - pymdownx.details\n - pymdownx.emoji:\n emoji_index: !!python/name:material.extensions.emoji.twemoji\n emoji_generator: !!python/name:material.extensions.emoji.to_svg\n options:\n custom_icons:\n - overrides/.icons\n - pymdownx.highlight:\n anchor_linenums: true\n line_spans: __span\n pygments_lang_class: true\n - pymdownx.inlinehilite\n - pymdownx.keys\n - pymdownx.smartsymbols\n - pymdownx.superfences:\n - pymdownx.tabbed:\n alternate_style: true\n - tables\n - md_in_html\n\n# Validation\nvalidation:\n nav:\n omitted_files: info\n not_found: warn\n absolute_links: info\n links:\n not_found: warn\n absolute_links: info\n unrecognized_links: info\n\nnot_in_nav: |\n **/download/*.md\n\n# Page tree\nnav:\n- Home: index.md\nCreate build/ folder for temporary files during migration.
mkdir build\nNote
If converting a maven project use of the existing target/ folder can be configured below.
Define .gitingore to avoid adding generated artifacts to version control.
__pycache__\ntarget\nbuild\n!.gitignore\nThe resulting directory structure is:
docs/\nsource/\n.gitignore\ndownload.py\nmkdocs.yml\nrequirements.txt\nOptional: If your content uses downloaddirective to include external content, there is a mkdocshook for processing of download.txtfiles.
Create download.py.
import glob\nimport logging\nimport mkdocs.plugins\nimport os\nimport shutil\n\nlog = logging.getLogger('mkdocs')\n\n\n@mkdocs.plugins.event_priority(-50)\ndef on_pre_build(config, **kwargs):\n docs_dir = config['docs_dir']\n # print(docs_dir)\n\n pattern = os.path.normpath(os.path.join(docs_dir, '**', 'download', 'download.txt'))\n\n for download_txt in glob.glob(pattern, recursive=True):\n download_folder = os.path.dirname(download_txt)\n donload_txt_path = os.path.relpath(download_txt,docs_dir)\n log.info(f\"Download {donload_txt_path} ...\")\n with open(download_txt, 'r') as file:\n path_list = file.read()\n\n for path in path_list.splitlines():\n if len(path.strip()) == 0 or path.startswith('#'):\n continue\n resolved = os.path.normpath(os.path.join(download_folder, path))\n if os.path.exists(resolved):\n dest = os.path.normpath(os.path.join(download_folder, os.path.basename(path)))\n if not os.path.exists(dest) or (os.stat(resolved).st_mtime - os.stat(dest).st_mtime > 1):\n print(f\"Download {dest}\")\n shutil.copyfile(resolved, dest, follow_symlinks=True)\n else:\n log.info(f\"Download '{resolved}' up to date\")\n else:\n log.warning(f\"Download '{resolved}' not found\")\nRegister hook with mkdocs.yml
# Customizations\nhooks:\n- download.py\nNote
See writing guide Download of external file for example on how to use this hook.
The resulting directory structure is:
docs/\nsource/\ndownload.py\nmkdocs.yml\nrequirements.txt\nFor simple python sphinx-build setup and directory structure no configuration is required.
Optional: To provide configuration for your project:
Create a translate.yml to configure script for your project.
# translate script configuration python project\nproject_folder: \".\"\ndocs_folder: \"docs\"\nbuild_folder: \"build\"\n\n# mkdocs migration\nrst_folder: \"source\"\nanchor_file: 'anchors.txt'\nconvert_folder: \"migrate\"\nsubstitutions:\n project: MkDocs Translation Example\n author: Open Source Geospatial Foundation\n copyright: 2024, Open Source Geospatial Foundation\n project_copyright: 2024, Open Source Geospatial Foundation\nextlinks:\n github: https://github.com/jodygarnett/translate/blob/main/%s\n release: https://github.com/jodygarnett/translate/releases/tag/{{ release }}|Release {{ release }}\n squidfunk: https://squidfunk.github.io/mkdocs-material/%s\nmacro_ignore:\n - setup/index.md\n\n# markdown internationalization\ndeepl_base_url: \"https://api-free.deepl.com\"\nupload_folder: \"upload\"\ndownload_folder: \"download\"\nNote
The example above is for the example project, with project and author substitutions. This project also has extlinks defined that need to be known upfront during migration.
Optional: Maven project translate.yml configuration recommendations.
# translate script configuration maven project\nproject_folder: \".\"\ndocs_folder: \"docs\"\nbuild_folder: \"target\"\n\n# mkdocs migration\nrst_folder: \"source\"\nanchor_file: 'anchors.txt'\nconvert_folder: \"migrate\"\n\n# markdown internationalization\ndeepl_base_url: \"https://api-free.deepl.com\"\nupload_folder: \"translate\"\ndownload_folder: \"translate\"\nThe resulting directory structure is:
docs/\nsource/\n.gitignore\ntranslate.yml\nmkdocs.yml\nrequirements.txt\nThe configuration settings are:
project_folder: . Default assumes you are running from the current directory.
docs_folder docs mkdocs convention.
build_folder build The use of build follows sphinx-build and mkdocs convention, maven projects may wish to use target.
rst_folder source Location of sphinx-build documentation to migrate to mkdocs.
anchor_file anchors.txt Name of index file used to lookup anchor and title information during migration.
convert_folder migrate Combined with build_folder for rst conversion temporary files (example: build/migrate. Temporary files are required for use by pandoc.
upload_folder upload Combined with build_folder to stage html files for internationalization (example: build/upload)
deepl_base_url: https://api-free.deepl.com Customize if you have a subscription to deepl.
download_folder download Combined with build_folder to retrieve internationalization results (example: build/download) Temporary files are required for use by pandoc.
substitutions dictionary of |substitutions|to use when converting config.py rst_epilog common substitutions.
project: GeoServer\nauthor: Open Source Geospatial Foundation\ncopyright: 2023, Open Source Geospatial Foundation\nproject_copyright: 2023, Open Source Geospatial Foundation\nThe built-in substitutions for {{ version }}and {{ release }}are changed to {{ version }} and {{ release }} variables for use with mkdocs-macros-pluginvariable substitution:
Use mkdocs.yml to define these variable substitutions:
extra:\n homepage: https://geoserver.org/\n version: '2.24'\n release: '2.24.2'\nextlinks dictionary of config.py extlinks substitutions taking the form:
extlinks:\n wiki: https://github.com/geoserver/geoserver/wiki/%s\n user: https://docs.geoserver.org/{{ branch }}/en/user/%s\n geos: https://osgeo-org.atlassian.net/browse/GEOS-%s|GEOS-%s\n download_release: https://sourceforge.net/projects/geoserver/files/GeoServer/{{ release }}/geoserver-{{ release }}-%s.zip|geoserver-{{ release }}-%s.zip\nNote
Use of mkdocs-macros-pluginfor variable substitution of releaseabove.
Use of |GEOS-%s to override default link text %s.
This handles the sphinx-build config.py extlinks during migration:
extlinks = {\n 'wiki': ('https://github.com/geoserver/geoserver/wiki/%s', '%s'),\n 'user': ('https://docs.geoserver.org/'+branch+'/en/user/%s', '%s'),\n 'geos': ('https://osgeo-org.atlassian.net/browse/GEOS-%s','GEOS-%s'),\n 'download_release': ('https://sourceforge.net/projects/geoserver/files/GeoServer/' + release + '/geoserver-' + release + '-%s.zip', 'geoserver-' + release + '-%s.zip )\n}\nmacro_ignore Use of mkdocs-macros-plugincan conflict with code examples.
This script adds the YAML header to enable macros to better support the use {{ version }}and {{ release }} If you find this accidentially is triggered by code examples you can add an ignore.
The translate script is used for migrating contents to mkdocs, and translating mkdocs content between languages.
To help manage a multi-language build is it kind to provide human translators with an example document to start from.
"},{"location":"translate/language/#setup","title":"Setup","text":"The mkdocs-static-i18n <https://ultrabug.github.io/mkdocs-static-i18n/>plugin is setup based on suffix, with index.md is the default English, and index.fr.md used for French:
| index.md\n| index.fr.md\n+ img/\n | figure.png\n + figure.fr.png\nThe configuration of mkdocs-static-i18n is represented in mkdocs.yml using:
plugins:\n - i18n:\n docs_structure: suffix\n reconfigure_material: true\n languages:\n - locale: en\n default: true\n name: English\n - locale: fr\n name: Fran\u00e7ais\n site_name: 'Aide en ligne'\n nav_translations:\n Home: Accueil\n Search: Recherche\nTranslation uses pandoc to convert to html and then using Deepl REST API.
Provide environmental variable with Deepl authentication key:
export DEEPL_AUTH=\"xxxxxxxx-xxx-...-xxxxx:fx\"\nTranslate a document to french using pandoc and deepl:
mkdocs_translate french docs/help/index.md\nTo translate several documents in a folder:
mkdocs_translate french docs/overview/*.md\nSee mkdocs_translate french --help for more options.
Keep in mind the following limitations:
Specific pandoc extensions are used to match the capabilities of mkdocs:
markdown extension pandoc extension tables pymdownx.keys pipe_tables pymdownx.superfences backtick_code_blocks admonition fenced_divsThe differences differences in markdown requires pre/post processing of markdown and html files. These steps are automated in the mkddoc_translate, supporting additionalmkdocs features requires updating this script.
"},{"location":"translate/migrate/","title":"Migrate","text":""},{"location":"translate/migrate/#preflight","title":"Preflight","text":"Use init to create docs directory and copy over non rst files (such as images and sample data).
mkdocs_translate init\nTo effectively migrate content the sphinx-build rst docs are scanned to collect information about the anchors, headings and downloads.
mkdocs_translate scan\nThe following is produced during preflight scans:
build/migrate/anchors.txt\ndocs/download/download.txt\ndocs/guide/download/download.txt\ndocs/setup/download/download.txt\nTroubleshooting:
You can run these scans independently:
mkdocs_translate scan download\nTo troubleshoot an individual file, the resulting indexcan be sent to standard out:
mkdocs_translate scan download --test source/setup/index.rst\nTo generate out navigation tree:
mkdocs_translate scan toc\n2. The output is printed to standard out and may be appended to mkdocs.yml file.
{% \n include \"../../mkdocs.yml\"\n start=\"# Page tree\"\n%}\nFormat conversion from sphinx-build reStructuredText files to mkdocs Markdown content.
To bulk convert all content from rst to md:
mkdocs_translate migrate\nReview this content you may find individual files to fix.
Some formatting is easier to fix in the rst files before conversion:
rst content is often incorrect, resulting in restarted numbering or block quotes.{.title-ref} snippets is a general indication to simplify the rst and re-translate.Troubleshooting:
Convert a single file:
mkdocs_translate migrate source/introduction/license.rst\nBulk convert files in a folder:
mkdocs_translate migrate source/introduction/**/*.rst\nSome things are not supported by pandoc, which will produce WARNING: messages:
Substitutions used for inline images
Underlines: replace with bold or italic
WARNING: broken reference 'getting_involved' link:getting_involved-broken.rst\nTranslation example for mkdocs_translatescript Release 0.9.
Note
This is an example project, see project README.md for most recent instructions.
The mkdocs_translate script is open-source using The MIT License (MIT).
"},{"location":"development/","title":"Development","text":""},{"location":"development/#local-development","title":"Local Development","text":"To build and test locally:
Clone:
git clone https://github.com/jodygarnett/translate.git translate\nInstall requirements:
cd translate\npip3 install -r mkdocs_translate/requirements.txt\nInstall locally:
pip3 install -e .\nRecommend troubleshooting a single file at a time:
mkdocs_translate migrate source/index.rst\nCompare the temporary files staged for pandoc conversion:
bbedit source/index.rst docs/index.md build/migrate/index.tmp.html build/migrate/index.tmp.md\nTo turn on logging during migrating a file:
mkdocs_translate --log=DEBUG migrate source/index.rst\nTo troubleshoot indexing when scanning a single document:
mkdocs_translate --log=DEBUG scan index --TEST source/index.rst\nThe index information is sent to standard out (rather than added to a anchor.txt file.
To troubleshoot downloads when scanning a single document:
mkdocs_translate --log=DEBUG scan download --TEST source/index.rst\nThe download information is sent to standard out (rather than a download.txt file.
The pandoc plugin settings are in two constants:
md_extensions_to =\n 'markdown+definition_lists+fenced_divs+backtick_code_blocks+fenced_code_attributes-simple_tables+pipe_tables'\nmd_extensions_from =\n 'markdown+definition_lists+fenced_divs+backtick_code_blocks+fenced_code_attributes+pipe_tables'\nThe pandoc extensions are chosen to align with mkdocs use of markdown extensions, or with post-processing:
markdown extension pandoc extension post processing tables pymdownx.keys pipe_tables post processing pymdownx.superfences backtick_code_blocks post processing admonition fenced_divs post processingLanguage translation depends on conversion to and from html. To troubleshoot just the markdown to html conversion:
mkdocs_translate internal_html docs/contributing/style-guide.md\nmkdocs_translate internal_markdown build/convert/contributing/style-guide.html\n\ndiff docs/contributing/style-guide.md build/convert/contributing/style-guide.md\nLangauge conversion uses text/htmlto avoid internationalization of content distributing markdown formatting.
Copyright \u00a9 2024 Jody Garnett
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"guide/","title":"Writing Guide","text":"Working with documentation, markdown formatting, and writing style guide.
Note
The mkdoc_translate script can adapt some markdown extensions for use with pandoc conversion, but not everything.
While it is fine to use the mkdoc_translate script for initial Content Migration, if you wish to continue using this tool for language translation you are advised to keep the following writing guidelines in mind.
Material for MkDocs
The writing guide is setup for use with the excellent Material for MkDocs.
This is a great project that was selected by the GeoNetwork community (primarily for the visual appeal). In practice it ends up being quite a nice way to \"keep up\" with advances in the mkdocs ecosystem without having to constantly research what is best.
"},{"location":"guide/markdown/","title":"Markdown","text":"These markdown conventions are carefully constructed for consistent representation of user interface elements, files, data and field input.
Markdown Directive strong gui label, menu selectionmonospace text input, item selection emphasis figure (caption) strong-emphasis application, command monospace-strong file Note
The above conventions are important for consistency and are required by the translation process.
As an example we do not wish to translate keyboard input, so these are represented as monospace text input.
"},{"location":"guide/markdown/#user-interface-components","title":"User interface components","text":"Use **strong**to name user interface components for interaction (press for buttons, click for link).
Preview:
Navigate to Data \u2192 Layers page, and press Add to create a new layer.
Markdown uses **strong**
Navigate to **Data > Layers** page,\nand press **Add** to create a new layer.\nRich structured text uses menuselectionand guilabeldirectives:
Navigate to **Data --> Layers** page,\nand press **Add** to create a new layer.\nUse item for user selected input, or item in a list or tree:
Preview:
Select Basemap layer.
Markdown uses monospace:
Select ``Basemap``layer.\nRich structured text uses monospace:
Select ``Basemap`` layer.\nUse monospace for user supplied text input:
Preview:
Use the Search field to enter: Ocean*
Markdown uses monospace:
Use the **Search** field enter: ``Ocean*``\nRich structured text uses kbd directive:
Use the **Search** field to enter: ``Ocean*``\nUse key directive for keyboard keys.
Preview:
Press Control-sto search.
Markdown uses mkdocs-material keys formatting:
Press ++control+s++ to search.\nRich structured text:
Press ``Control-s``to search.\nUse definition list to document data entry. The field names use strong as they name a user interface element. Field values to input uses monspace as user input to type in.
Preview:
To login as the GeoServer administrator using the default password:
User:admin
geoserver
Unchecked
Press Login.
Markdown: definition lists
1. To login as the GeoServer administrator using the default password:\n\n **User**\n\n : ``admin``\n\n **Password**\n\n : ``geoserver``\n\n **Remember me**\n\n : Unchecked\n\n Press **Login**.\nRich structured text: list-table
#. To login as the GeoServer administrator using the default password:\n\n .. list-table::\n :widths: 30 70\n :width: 100%\n :stub-columns: 1\n\n * - User:\n - ``admin`` * - Password:\n - ``geoserver`` * - Remember me\n - Unchecked\n\n Press **Login**.\nUse bold with italics for proper names of applications, commands, tools, and products.
Preview:
Launch pgAdmin and connect to the tutorial database.
Markdown:
Launch ***pgAdmin*** and connect to the ``tutorial``database.\nRich structured text uses command directive:
Launch ***pgAdmin*** and connect to the ``tutorial`` database.\nUse bold with monospace for files and folders:
Preview
See configuration file WEB-INF/config-security/config-security-ldap.xml for details
Markdown:
See configuration file\n**`WEB-INF/config-security/config-security-ldap.xml`**\nfor details\nRich structured text:
See configuration\nfile **`WEB-INF/config-security/config-security-ldap.xml`**\nfor details\nReference to other section of the document (some care is required to reference a specific heading):
Authors have access to translation for initial draft.
Markdown use of relative links and anchor:
Authors have access to [translation](../translate/language#translate) for initial draft.\nreStructuredText use of ref directive:
Authors have access to `translation <../translate/language.rst#translate>`_ for initial draft.\nSample file included in the documentation:
Download schema example.txt.
Markdown relative link, with text following bold with monospacefile convention above:
Download text [**`example.txt`**](files/example.txt).\nYou may also experiment with mkdocs attr_list to supply a filename:
Download text [**`example.txt`**](files/example.txt) {:download=\"example.txt\"} .\nreStructured text uses downlaod directive:
Download text `example.txt <files/example.txt>`__.\nTo include sample file from outside of the documentation tree:
Open-source LICENSE.md
Note
This functionality is not supported by Material for mkdocs (or any plugin I could find). It is accomplished using the download.py hook described in setup.
To use download.py hook, create a download folder to hold staged files
Markdown refers to this folder using a relative link (like normal):
Open-source [**`LICENSE.md`**](download/LICENSE.md)\nCreate download/download.txt with list of files to stage during mkdocs build process:
# files list for mkdocs hook staging download content\n\nLICENSE.md=../../../../LICENSE.md\nreStructuredText uses download directive with relative path (you may starting leading / to indicate the root of the documentation source folder):
Open-source `LICENSE.md <download/LICENSE.md>`__\nMaterial for mkDocs has extensive icon support, for many user interface elements we can directly make use of the appropriate icon in Markdown:
1. Press the *Validate :fontawesome-solid-check:* button at the top of the page.\nCustom icons:
Empower everyone with open source geospatial
Material for MkDocs provides support for custom icons:
:osgeo-logo: Empower everyone with open source geospatial\nAdd images to overrides/.icons/ (yes it is a hidden folder):
overrides/\n- .icons/\n - osgeo/\n logo.svg\nreStructuredText does not offer custom icons, the closest is the use of substitutions to \"inline\" and image.
.. |osgeo_mark| image:: img/osgeo_mark.svg\n :width: 20\n :height: 20\n\n|osgeo_mark| Empower everyone with open source geospatial\nWarning
The mkdocs_translate and pandoc combo is unable to convert inline images at this time.
[WARNING] Reference not found for 'Key \"osgeo_mark\"' at build/migrate/guide/markdown.tmp.prep.rst_chunk line 5 column 13\nFigures are used frequently to allow a caption to describe screen shots and diagrams.
Free and Open Source Software for Geospatial
Markdown handles figures are handled by convention adding emphasized text after each image.
\n*Free and Open Source Software for Geospatial*\nNote
The convention above depends on CSS rules in overrides/assets/stylesheets/extra.css to provide a consistent presentation:
img + em, .browser-border + em, .browser-mockup + em {\n display: block;\n text-align: left;\n font-size: 0.7rem;\n font-style: normal;\n}\nNote
The official Material for MkDocs answer for images with captions is to use md_in_html extension:
<figure markdown=\"span\">\n { scale=\"25%\" }\n <figcaption>Free and Open Source Software for Geospatial</figcaption>\n</figure>\nreStructuredText has a figure directive:
.. code-block:: raw_markdown\n\n \n *Free and Open Source Software for Geospatial*\nImage content:
Markdown provides inline image syntax.
\nUse of mkdocs att_list can be used to adjust scale:
{ scale=\"25%\" }\nreStructuredText has an image directive:
.. image:: img/foss4g.svg\n :scale: 25%\nMaterial for MkDocs :squidfunkdata tables <reference/data-tables/> use pipe-tables approach (supported by both mkdocs and pandoc):
Leading ` | tailing ```:
| First Header | Second Header | Third Header |\n|--------------|---------------|--------------|\n| Content Cell | Content Cell | Content Cell |\n| Content Cell | Content Cell | Content Cell |\nColumn alignment using :
| First Header | Second Header | Third Header |\n|:-------------|:-------------:|-------------:|\n| Left | Center | Right |\n| Left | Center | Right |\nUse of mkdocs-include-plugin provides ability to inline content. Example project uses following mkdocs.yml setup:
plugins:\n - include-markdown:\n preserve_includer_indent: true\n dedent: true\n comments: false\nThe official Material for mkdocs guidance is to use snippets however this did not offer the ability to include code examples and configuration from outside the document tree.
Reference
Inlining a snippet from another file is helpful for material such as disclaimers or statements which are repeated in text.
Empower everyone with open source geospatial
Here is a snippet to include markdown files inline, requires opening tag {% and closing tag %}:
{/\n include-markdown 'files/vision_statement.txt'\n/}\nNote
Placeholders {/and /}used to indicate location of {%and %}in above code example.
Writers can use include-markdown with a glob pattern to inline many files, and an option to adjusting header level. Together these two features can be used break up longer pages into more manageable size.
This takes the place of the sphinx-build include directive:
.. include:: files/vision_statement.txt\nNote
You may wish to use the txt extension for included content. If you wish to use md extension you can adjust mkdocs.yml exclude or not not_in_nav to address warnings.
plugins:\n - exclude:\n glob:\n - '**/files/*.md'\nIncluding configuration and code examples:
<CharacterString>da165110-88fd-11da-a88f-000d939bc5d8</CharacterString>\nUse includeto include normal files, with optional use of start and end markers to capture a snippet, and dedent for appearance.
In this case we are including content into an xml code block to provide syntax highlighting, requires opening tag {% and closing tag %} within the code block:
``` xml\n{/\n include 'files/record.xml'\n dedent=\"true\"\n start=\"<!--start-->\"\n end=\"<!--end-->\"\n/}\n```\nNote
Placeholders {/and /}used to indicate location of {%and %}in above code example.
This takes the place of the sphinx-build literal-include directive:
.. literalinclude:: files/record.xml\n :language: xml\n :start-after: <!--start-->\n :end-before: <!--end-->\n :dedent:\nWriting style guide to help creating consistent documentation.
This style guide is useful as a reference when reviewing pull-requests for documentation.
Reference
Documentation should be concise and not just a brain dump. Reference material should contain short pages and be easy to refer to without having to scroll through a large volume of text. Tutorials can be longer, depending on scope. If the point of the document is to share your thoughts and insights, it belongs in a blog post. This documentation is a manual, not a wiki.
"},{"location":"guide/style/#avoid-marketing","title":"Avoid marketing","text":"If the point of the document is to showcase a new feature it does not belong in the documentation. Write an article or a blog post about it. If it is necessary to point out a technical benefit of a feature then do so from a technical standpoint.
Bad
Sub-Portals are a great way to provide a team with their own catalogue!
Good
Sub-Portals define a distinct catalogue for use.
"},{"location":"guide/style/#be-professional","title":"Be professional","text":"Avoid the use of slang or other \"colorful\" language. The point of a technical document is to be informative, not to keep the reader amused. Avoiding slang helps keep the document accessible to as large an audience as possible.
Bad
Good
When providing step-by-step instructions, number steps and use direct commands or requests. Avoid the use of \"we\" and \"let's\".
Bad
Now let's select a record by ...
Good
Reference
Each word in the page name should be capitalized except for articles (such as \"the\", \"a\", \"an\") and conjunctions (such as \"and\", \"but\", \"or\"). A page name should never start with an article.
Bad
Adding a wms or wfs service
Good
Adding a WMS or WFS service
Bad
The Harvester Tutorial
Good
Harvester Tutorial
"},{"location":"guide/style/#capitalization-of-section-names","title":"Capitalization of section names","text":"Do not capitalize second and subsequent words unless the title is almost always capitalized in English (like proper names). Thus, capitalize John Wayne and Art Nouveau, but not Video Games.
Bad
Creating a New Record
Good
Creating a new record
"},{"location":"guide/style/#verb-usage","title":"Verb usage","text":"It is recommended that the gerund (the -ing form in English) be used unless there is a more common noun form. For example, an article on swimming is better than one on swim.
Bad
Create a new datastore
Good
Creating a new datastore
"},{"location":"guide/style/#avoid-plurals","title":"Avoid plurals","text":"Create page titles that are in the singular. Exceptions to this are nouns that are always plural (scissors, trousers), a small class that requires a plural (polar coordinates, Bantu languages, The Beatles).
Bad
templates tutorial
Good
Template tutorial
"},{"location":"guide/style/#formatting","title":"Formatting","text":""},{"location":"guide/style/#code-and-command-line","title":"Code and command line","text":"Any code or command line snippets should be formatted as code:
{\n \"code\": \"This is a code block.\"\n}\nWhen lines are longer than 80 characters, extend multiple lines in a format appropriate for the language in use. If possible, snippets should be functional when pasted directly into the appropriate target.
For example, XML make no distinction between a single space and multiple spaces, so the following snippets are fine:
<namespace:tagname attributename=\"attributevalue\" attribute2=\"attributevalue\"\n nextattribute=\"this is on another line\"/>\nFor shell scripts, new lines can be escaped with a backslash character ([]{.title-ref}).
mvn clean install \\\n -DskipTests\nBUILD SUCCESS\nIt is helpful to separate out input from output, so that the command can be easily copied as shown above.
"},{"location":"guide/download/LICENSE/","title":"The MIT License (MIT)","text":"Copyright \u00a9 2024 Jody Garnett
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"setup/","title":"Getting started","text":""},{"location":"setup/#install","title":"Installation","text":"A translate script is provided to facilitate working with pandoc and deepl translation services.
To install development version use:
pip install git+https://github.com/jodygarnett/translate.git\nInstall script requirements, and check it runs:
mkdocs_translate --help\nThis script requires pandoc be installed:
Ubuntu:
apt-get install pandoc\nmacOS:
brew install pandoc\nReference
A working example is provided to be adapted for your project.
Create requirements.txt with mkdocs plugins required.
mkdocs-material>=9.5.9\nmkdocs-include-markdown-plugin>=6.0.4\nmkdocs-exclude>=1.0.2\nmkdocs-macros-plugin>=1.0.4\nCreate mkdocs.yml, the navigation tree is initially empty.
# Project information\nsite_name: MkDocs Translate\nsite_description: Example sphinx-build documentation project for use with mkdocs_translate script.\n\nsite_dir: build/html\nsite_url: http://jodygarnett.github.io/translate\n\n# Repository\nrepo_name: translate\nrepo_url: https://github.com/jodygarnett/translate\nedit_uri: edit/main/example/docs\n\n# Copyright\ncopyright: Copyright © 2024 Open Source Geospatial Foundation\n\nextra_css:\n - assets/stylesheets/extra.css\n\n# Configuration\ntheme:\n name: material\n language: en\n custom_dir: overrides\n # logo: assets/images/geoserver_mark.png\n # favicon: assets/images/geoserver_mark.png\n icon:\n repo: fontawesome/brands/github\n palette:\n # Palette toggle for light mode\n - media: \"(prefers-color-scheme: light)\"\n scheme: default\n primary: blue\n toggle:\n icon: material/weather-night\n name: Switch to dark mode\n # Palette toggle for dark mode\n - media: \"(prefers-color-scheme: dark)\"\n scheme: slate\n toggle:\n icon: material/weather-sunny\n name: Switch to light mode\n features:\n - content.action.view\n - content.action.edit\n - content.code.copy\n - content.tabs.link\n - navigation.tracking\n - navigation.prune\n - navigation.indexes\n - toc.follow\n - navigation.top\n - navigation.footer\n - announce.dismiss\n\n# Plugins - install using: pip3 install -r requirements.txt\nplugins:\n - exclude:\n glob:\n - '**/download/download.txt'\n - include-markdown:\n preserve_includer_indent: true\n dedent: true\n comments: false\n - macros:\n render_by_default: false\n on_error_fail: true\n on_undefined: strict\n j2_block_start_string: '[[%'\n j2_block_end_string: '%]]'\n - search\n\n# Customizations\nhooks:\n - download.py\nextra:\n homepage: http://jodygarnett.github.io/translate\n social:\n - icon: fontawesome/brands/github\n link: ttps://github.com/jodygarnett/translate\n version: '0.9'\n release: '0.9'\n\n# Extensions\n# - These are carefully chosen to work with pandoc markdown support for whole document translation\nmarkdown_extensions:\n - admonition\n - attr_list\n - def_list\n - pymdownx.details\n - pymdownx.emoji:\n emoji_index: !!python/name:material.extensions.emoji.twemoji\n emoji_generator: !!python/name:material.extensions.emoji.to_svg\n options:\n custom_icons:\n - overrides/.icons\n - pymdownx.highlight:\n anchor_linenums: true\n line_spans: __span\n pygments_lang_class: true\n - pymdownx.inlinehilite\n - pymdownx.keys\n - pymdownx.smartsymbols\n - pymdownx.superfences:\n - pymdownx.tabbed:\n alternate_style: true\n - tables\n - md_in_html\n\n# Validation\nvalidation:\n nav:\n omitted_files: info\n not_found: warn\n absolute_links: info\n links:\n not_found: warn\n absolute_links: info\n unrecognized_links: info\n\nnot_in_nav: |\n **/download/*.md\n\n# Page tree\nnav:\n- Home: index.md\nCreate build/ folder for temporary files during migration.
mkdir build\nNote
If converting a maven project use of the existing target/ folder can be configured below.
Define .gitingore to avoid adding generated artifacts to version control.
__pycache__\ntarget\nbuild\n!.gitignore\nThe resulting directory structure is:
docs/\nsource/\n.gitignore\ndownload.py\nmkdocs.yml\nrequirements.txt\nOptional: If your content uses downloaddirective to include external content, there is a mkdocshook for processing of download.txtfiles.
Create download.py.
import glob\nimport logging\nimport mkdocs.plugins\nimport os\nimport shutil\n\nlog = logging.getLogger('mkdocs')\n\n\n@mkdocs.plugins.event_priority(-50)\ndef on_pre_build(config, **kwargs):\n docs_dir = config['docs_dir']\n # print(docs_dir)\n\n pattern = os.path.normpath(os.path.join(docs_dir, '**', 'download', 'download.txt'))\n\n for download_txt in glob.glob(pattern, recursive=True):\n download_folder = os.path.dirname(download_txt)\n donload_txt_path = os.path.relpath(download_txt,docs_dir)\n log.info(f\"Download {donload_txt_path} ...\")\n with open(download_txt, 'r') as file:\n path_list = file.read()\n\n for path in path_list.splitlines():\n if len(path.strip()) == 0 or path.startswith('#'):\n continue\n resolved = os.path.normpath(os.path.join(download_folder, path))\n if os.path.exists(resolved):\n dest = os.path.normpath(os.path.join(download_folder, os.path.basename(path)))\n if not os.path.exists(dest) or (os.stat(resolved).st_mtime - os.stat(dest).st_mtime > 1):\n print(f\"Download {dest}\")\n shutil.copyfile(resolved, dest, follow_symlinks=True)\n else:\n log.info(f\"Download '{resolved}' up to date\")\n else:\n log.warning(f\"Download '{resolved}' not found\")\nRegister hook with mkdocs.yml
# Customizations\nhooks:\n- download.py\nNote
See writing guide Download of external file for example on how to use this hook.
The resulting directory structure is:
docs/\nsource/\ndownload.py\nmkdocs.yml\nrequirements.txt\nFor simple python sphinx-build setup and directory structure no configuration is required.
Optional: To provide configuration for your project:
Create a translate.yml to configure script for your project.
# translate script configuration python project\nproject_folder: \".\"\ndocs_folder: \"docs\"\nbuild_folder: \"build\"\n\n# mkdocs migration\nrst_folder: \"source\"\nanchor_file: 'anchors.txt'\nconvert_folder: \"migrate\"\nsubstitutions:\n project: MkDocs Translation Example\n author: Open Source Geospatial Foundation\n copyright: 2024, Open Source Geospatial Foundation\n project_copyright: 2024, Open Source Geospatial Foundation\nextlinks:\n github: https://github.com/jodygarnett/translate/blob/main/%s\n release: https://github.com/jodygarnett/translate/releases/tag/{{ release }}|Release {{ release }}\n squidfunk: https://squidfunk.github.io/mkdocs-material/%s\nmacro_ignore:\n - setup/index.md\n\n# markdown internationalization\ndeepl_base_url: \"https://api-free.deepl.com\"\nupload_folder: \"upload\"\ndownload_folder: \"download\"\nNote
The example above is for the example project, with project and author substitutions. This project also has extlinks defined that need to be known upfront during migration.
Optional: Maven project translate.yml configuration recommendations.
# translate script configuration maven project\nproject_folder: \".\"\ndocs_folder: \"docs\"\nbuild_folder: \"target\"\n\n# mkdocs migration\nrst_folder: \"source\"\nanchor_file: 'anchors.txt'\nconvert_folder: \"migrate\"\n\n# markdown internationalization\ndeepl_base_url: \"https://api-free.deepl.com\"\nupload_folder: \"translate\"\ndownload_folder: \"translate\"\nThe resulting directory structure is:
docs/\nsource/\n.gitignore\ntranslate.yml\nmkdocs.yml\nrequirements.txt\nThe configuration settings are:
project_folder: . Default assumes you are running from the current directory.
docs_folder docs mkdocs convention.
build_folder build The use of build follows sphinx-build and mkdocs convention, maven projects may wish to use target.
rst_folder source Location of sphinx-build documentation to migrate to mkdocs.
anchor_file anchors.txt Name of index file used to lookup anchor and title information during migration.
convert_folder migrate Combined with build_folder for rst conversion temporary files (example: build/migrate. Temporary files are required for use by pandoc.
upload_folder upload Combined with build_folder to stage html files for internationalization (example: build/upload)
deepl_base_url: https://api-free.deepl.com Customize if you have a subscription to deepl.
download_folder download Combined with build_folder to retrieve internationalization results (example: build/download) Temporary files are required for use by pandoc.
substitutions dictionary of |substitutions|to use when converting config.py rst_epilog common substitutions.
project: GeoServer\nauthor: Open Source Geospatial Foundation\ncopyright: 2023, Open Source Geospatial Foundation\nproject_copyright: 2023, Open Source Geospatial Foundation\nThe built-in substitutions for {{ version }}and {{ release }}are changed to {{ version }} and {{ release }} variables for use with mkdocs-macros-pluginvariable substitution:
Use mkdocs.yml to define these variable substitutions:
extra:\n homepage: https://geoserver.org/\n version: '2.24'\n release: '2.24.2'\nextlinks dictionary of config.py extlinks substitutions taking the form:
extlinks:\n wiki: https://github.com/geoserver/geoserver/wiki/%s\n user: https://docs.geoserver.org/{{ branch }}/en/user/%s\n geos: https://osgeo-org.atlassian.net/browse/GEOS-%s|GEOS-%s\n download_release: https://sourceforge.net/projects/geoserver/files/GeoServer/{{ release }}/geoserver-{{ release }}-%s.zip|geoserver-{{ release }}-%s.zip\nNote
Use of mkdocs-macros-pluginfor variable substitution of releaseabove.
Use of |GEOS-%s to override default link text %s.
This handles the sphinx-build config.py extlinks during migration:
extlinks = {\n 'wiki': ('https://github.com/geoserver/geoserver/wiki/%s', '%s'),\n 'user': ('https://docs.geoserver.org/'+branch+'/en/user/%s', '%s'),\n 'geos': ('https://osgeo-org.atlassian.net/browse/GEOS-%s','GEOS-%s'),\n 'download_release': ('https://sourceforge.net/projects/geoserver/files/GeoServer/' + release + '/geoserver-' + release + '-%s.zip', 'geoserver-' + release + '-%s.zip )\n}\nmacro_ignore Use of mkdocs-macros-plugincan conflict with code examples.
This script adds the YAML header to enable macros to better support the use {{ version }}and {{ release }} If you find this accidentially is triggered by code examples you can add an ignore.
The translate script is used for migrating contents to mkdocs, and translating mkdocs content between languages.
To help manage a multi-language build is it kind to provide human translators with an example document to start from.
"},{"location":"translate/language/#setup","title":"Setup","text":"The mkdocs-static-i18n <https://ultrabug.github.io/mkdocs-static-i18n/>plugin is setup based on suffix, with index.md is the default English, and index.fr.md used for French:
| index.md\n| index.fr.md\n+ img/\n | figure.png\n + figure.fr.png\nThe configuration of mkdocs-static-i18n is represented in mkdocs.yml using:
plugins:\n - i18n:\n docs_structure: suffix\n reconfigure_material: true\n languages:\n - locale: en\n default: true\n name: English\n - locale: fr\n name: Fran\u00e7ais\n site_name: 'Aide en ligne'\n nav_translations:\n Home: Accueil\n Search: Recherche\nTranslation uses pandoc to convert to html and then using Deepl REST API.
Provide environmental variable with Deepl authentication key:
export DEEPL_AUTH=\"xxxxxxxx-xxx-...-xxxxx:fx\"\nTranslate a document to french using pandoc and deepl:
mkdocs_translate french docs/help/index.md\nTo translate several documents in a folder:
mkdocs_translate french docs/overview/*.md\nSee mkdocs_translate french --help for more options.
Keep in mind the following limitations:
Specific pandoc extensions are used to match the capabilities of mkdocs:
markdown extension pandoc extension tables pymdownx.keys pipe_tables pymdownx.superfences backtick_code_blocks admonition fenced_divsThe differences differences in markdown requires pre/post processing of markdown and html files. These steps are automated in the mkddoc_translate, supporting additionalmkdocs features requires updating this script.
"},{"location":"translate/migrate/","title":"Migrate","text":""},{"location":"translate/migrate/#preflight","title":"Preflight","text":"Use init to create docs directory and copy over non rst files (such as images and sample data).
mkdocs_translate init\nTo effectively migrate content the sphinx-build rst docs are scanned to collect information about the anchors, headings and downloads.
mkdocs_translate scan\nThe following is produced during preflight scans:
build/migrate/anchors.txt\ndocs/download/download.txt\ndocs/guide/download/download.txt\ndocs/setup/download/download.txt\nTroubleshooting:
You can run these scans independently:
mkdocs_translate scan download\nTo troubleshoot an individual file, the resulting indexcan be sent to standard out:
mkdocs_translate scan download --test source/setup/index.rst\nTo generate out navigation tree:
mkdocs_translate scan toc\n2. The output is printed to standard out and may be appended to mkdocs.yml file.
{% \n include \"../../mkdocs.yml\"\n start=\"# Page tree\"\n%}\nFormat conversion from sphinx-build reStructuredText files to mkdocs Markdown content.
To bulk convert all content from rst to md:
mkdocs_translate migrate\nReview this content you may find individual files to fix.
Some formatting is easier to fix in the rst files before conversion:
rst content is often incorrect, resulting in restarted numbering or block quotes.{.title-ref} snippets is a general indication to simplify the rst and re-translate.Troubleshooting:
Convert a single file:
mkdocs_translate migrate source/introduction/license.rst\nBulk convert files in a folder:
mkdocs_translate migrate source/introduction/**/*.rst\nSome things are not supported by pandoc, which will produce WARNING: messages:
Substitutions used for inline images
Underlines: replace with bold or italic
WARNING: broken reference 'getting_involved' link:getting_involved-broken.rst\n