From 9d0e59d79e35882b29de3a4fff16aab8c2c3a436 Mon Sep 17 00:00:00 2001 From: Jody Garnett Date: Fri, 23 Feb 2024 13:24:00 -0800 Subject: [PATCH] Deployed ced68f5 with MkDocs version: 1.5.3 --- development/index.html | 2 +- guide/files/copy_me | 1 + guide/markdown/index.html | 56 ++++++++++++++++++---------------- index.html | 2 +- search/search_index.json | 2 +- setup/index.html | 38 +++++++++++------------ sitemap.xml | 22 ++++++------- sitemap.xml.gz | Bin 294 -> 295 bytes translate/language/index.html | 4 +-- translate/migrate/index.html | 2 +- 10 files changed, 67 insertions(+), 62 deletions(-) create mode 100644 guide/files/copy_me diff --git a/development/index.html b/development/index.html index 20e4534..ec63b38 100644 --- a/development/index.html +++ b/development/index.html @@ -658,7 +658,7 @@

Pandoc

diff docs/contributing/style-guide.md build/convert/contributing/style-guide.md -

Langauge conversion uses text/htmlto avoid internationalization of content distributing markdown formatting.

+

Langauge conversion uses text/html to avoid internationalization of content distributing markdown formatting.

diff --git a/guide/files/copy_me b/guide/files/copy_me new file mode 100644 index 0000000..e18425a --- /dev/null +++ b/guide/files/copy_me @@ -0,0 +1 @@ +This is an example of a file without an extension used to double check init will copy such a file. \ No newline at end of file diff --git a/guide/markdown/index.html b/guide/markdown/index.html index 026ff93..8dc4744 100644 --- a/guide/markdown/index.html +++ b/guide/markdown/index.html @@ -1002,16 +1002,16 @@

Markdown

As an example we do not wish to translate keyboard input, so these are represented as monospace text input.

User interface components

-

Use **strong**to name user interface components for interaction (press for buttons, click for link).

+

Use **strong** to name user interface components for interaction (press for buttons, click for link).

Preview:

Navigate to Data → Layers page, and press Add to create a new layer.

-

Markdown uses **strong**

+

Markdown uses **strong**:

Navigate to **Data > Layers** page,
 and press **Add** to create a new layer.
-

Rich structured text uses menuselectionand guilabeldirectives:

+

Rich structured text uses menuselection and guilabel directives:

Navigate to **Data --> Layers** page,
 and press **Add** to create a new layer.
@@ -1022,7 +1022,7 @@

Selected input

Select Basemap layer.

Markdown uses monospace:

-
Select ``Basemap``layer.
+
Select `Basemap` layer.
 

 
Rich structured text uses monospace:

 
Select ``Basemap`` layer.
@@ -1034,7 +1034,7 @@ 
Input text

 
Use the Search field to enter: Ocean*

 
 
Markdown uses monospace:

-
Use the **Search** field enter: ``Ocean*``
+
Use the **Search** field enter: `Ocean*`
 

 
Rich structured text uses kbd directive:

 
Use the **Search** field to enter: ``Ocean*``
@@ -1043,13 +1043,13 @@ 
Keypress

 
Use key directive for keyboard keys.

 
Preview:

 

-
Press Control-sto search.

+
Press Control-s to search.

 

 
Markdown uses mkdocs-material keys formatting:

 
Press ++control+s++ to search.
 

 
Rich structured text:

-
Press ``Control-s``to search.
+
Press `Control-s` to search.
 

 
Form input

 
Use 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.

@@ -1081,17 +1081,19 @@ 
Form input

 
     **User**
 
-    :   ``admin``
+    :   `admin`
 
-    **Password**
-
-    :   ``geoserver``
-
-    **Remember me**
+
+    **Password**
+
+    :   `geoserver`
+
 
-    :   Unchecked
+    **Remember me**
 
-    Press **Login**.
+    :   Unchecked
+
+    Press **Login**.
 

 
Rich structured text: list-table

 
#. To login as the GeoServer administrator using the default password:
@@ -1102,11 +1104,13 @@ 
Form input

       :stub-columns: 1
 
       * - User:
-        - ``admin``         * - Password:
-        - ``geoserver``         * - Remember me
-        - Unchecked
-
-   Press **Login**.
+        - `admin`
+      * - Password:
+        - `geoserver`
+      * - Remember me
+        - Unchecked
+
+   Press **Login**.
 

 
Applications, commands and tools

 
Use bold with italics for proper names of applications, commands, tools, and products.

@@ -1115,7 +1119,7 @@ 
Applications, commands and tools

 
Launch pgAdmin and connect to the tutorial database.

 
 
Markdown:

-
Launch ***pgAdmin*** and connect to the ``tutorial``database.
+
Launch ***pgAdmin*** and connect to the `tutorial` database.
 

 
Rich structured text uses command directive:

 
Launch ***pgAdmin*** and connect to the ``tutorial`` database.
@@ -1153,7 +1157,7 @@ 
Download of sample file

 

 
Download schema example.txt.

 

-
Markdown relative link, with text following bold with monospacefile convention above:

+
Markdown relative link, with text following bold with monospace file convention above:

 
Download text [**`example.txt`**](files/example.txt).
 

 
You may also experiment with mkdocs attr_list to supply a filename:

@@ -1268,7 +1272,7 @@ 
Images

 

 
Tables

 
Material for MkDocs :squidfunkdata tables <reference/data-tables/> use pipe-tables approach (supported by both mkdocs and pandoc):

-
Leading ` | tailing ```:

+
Leading | tailing |:

 
| First Header | Second Header | Third Header |
 |--------------|---------------|--------------|
 | Content Cell | Content Cell  | Content Cell |
@@ -1308,7 +1312,7 @@ 
include content

 

 

 
Note

-
Placeholders {/and /}used to indicate location of {%and %}in above code example.

+
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:

@@ -1329,7 +1333,7 @@ 
include config and code

 
<CharacterString>da165110-88fd-11da-a88f-000d939bc5d8</CharacterString>
 

 
-
Use includeto include normal files, with optional use of start and end markers to capture a snippet, and dedent for appearance.

+
Use include to 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
 {/
@@ -1342,7 +1346,7 @@ 
include config and code

 

 

 
Note

-
Placeholders {/and /}used to indicate location of {%and %}in above code example.

+
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
diff --git a/index.html b/index.html
index e028a2d..9f8a952 100644
--- a/index.html
+++ b/index.html
@@ -470,7 +470,7 @@
 
 
 
MkDocs Translate

-
Translation example for mkdocs_translatescript Release 0.9.

+
Translation example for mkdocs_translate script Release 0.9.

 

 
    
 
  • Getting started
    • 
diff --git a/search/search_index.json b/search/search_index.json
index 526743d..76a08b2 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"MkDocs Translate","text":"
    Translation example for mkdocs_translatescript Release 0.9.
     
       
    • Getting started
      •  
    • Translate Script
      •  
    • Writing Guide
      •  
    • Development
      •  
     
    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:
     
       
    1.  
      Clone:
       
      git clone https://github.com/jodygarnett/translate.git translate\n
       
      2.  
    2.  
      Install requirements:
       
      cd translate\npip3 install -r mkdocs_translate/requirements.txt\n
       
      3.  
    3.  
      Install locally:
       
      pip3 install -e .\n
       
      4.  
    "},{"location":"development/#debugging","title":"Debugging","text":"
       
    1.  
      Recommend troubleshooting a single file at a time:
       
      mkdocs_translate migrate source/index.rst\n
       
      2.  
    2.  
      Compare the temporary files staged for pandoc conversion:
       
      bbedit source/index.rst docs/index.md build/migrate/index.tmp.html build/migrate/index.tmp.md\n
       
      3.  
    3.  
      To turn on logging during migrating a file:
       
      mkdocs_translate --log=DEBUG migrate source/index.rst\n
       
      4.  
    4.  
      To troubleshoot indexing when scanning a single document:
       
      mkdocs_translate --log=DEBUG scan index --TEST source/index.rst\n
       
      The index information is sent to standard out (rather than added to a anchor.txt file.
       
      5.  
    5.  
      To troubleshoot downloads when scanning a single document:
       
      mkdocs_translate --log=DEBUG scan download --TEST source/index.rst\n
       
      The download information is sent to standard out (rather than a download.txt file.
       
      6.  
    "},{"location":"development/#pandoc","title":"Pandoc","text":"
       
    1.  
      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'\n
       
      2.  
    2.  
      The 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 processing 
      3.  
    3.  
      Language 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\n
       
      Langauge conversion uses text/htmlto avoid internationalization of content distributing markdown formatting.
       
      4.  
    "},{"location":"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":"guide/","title":"Writing Guide","text":"
    Working with documentation, markdown formatting, and writing style guide.
     
       
    • Markdown
      •  
    • 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 selection monospace 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.\n
     
    Rich structured text uses menuselectionand guilabeldirectives:
     
    Navigate to **Data --> Layers** page,\nand press **Add** to create a new layer.\n
    "},{"location":"guide/markdown/#selected-input","title":"Selected input","text":"
    Use item for user selected input, or item in a list or tree:
     
    Preview:
     
    Select Basemap layer.
     
    Markdown uses monospace:
     
    Select ``Basemap``layer.\n
     
    Rich structured text uses monospace:
     
    Select ``Basemap`` layer.\n
    "},{"location":"guide/markdown/#input-text","title":"Input text","text":"
    Use monospace for user supplied text input:
     
    Preview:
     
    Use the Search field to enter: Ocean*
     
    Markdown uses monospace:
     
    Use the **Search** field enter: ``Ocean*``\n
     
    Rich structured text uses kbd directive:
     
    Use the **Search** field to enter: ``Ocean*``\n
    "},{"location":"guide/markdown/#keypress","title":"Keypress","text":"
    Use key directive for keyboard keys.
     
    Preview:
     
    Press Control-sto search.
     
    Markdown uses mkdocs-material keys formatting:
     
    Press ++control+s++ to search.\n
     
    Rich structured text:
     
    Press ``Control-s``to search.\n
    "},{"location":"guide/markdown/#form-input","title":"Form input","text":"
    Use 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:
     
       
    1.  
      To login as the GeoServer administrator using the default password:
       User: 
      admin
       Password: 
      geoserver
       Remember me 
      Unchecked
       
      Press Login.
       
      2.  
     
    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**.\n
     
    Rich 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**.\n
    "},{"location":"guide/markdown/#applications-commands-and-tools","title":"Applications, commands and tools","text":"
    Use 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.\n
     
    Rich structured text uses command directive:
     
    Launch ***pgAdmin*** and connect to the ``tutorial`` database.\n
    "},{"location":"guide/markdown/#files","title":"Files","text":"
    Use 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\n
     
    Rich structured text:
     
    See configuration\nfile **`WEB-INF/config-security/config-security-ldap.xml`**\nfor details\n
    "},{"location":"guide/markdown/#links-and-references","title":"Links and references","text":""},{"location":"guide/markdown/#internal-references","title":"Internal References","text":"
    Reference 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.\n
     
    reStructuredText use of ref directive:
     
    Authors have access to `translation <../translate/language.rst#translate>`_ for initial draft.\n
    "},{"location":"guide/markdown/#download-of-sample-file","title":"Download of sample file","text":"
    Sample 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).\n
     
    You may also experiment with mkdocs attr_list to supply a filename:
     
    Download text [**`example.txt`**](files/example.txt) {:download=\"example.txt\"} .\n
     
    reStructured text uses downlaod directive:
     
    Download text `example.txt <files/example.txt>`__.\n
    "},{"location":"guide/markdown/#download_external","title":"Download of external file","text":"
    To 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)\n
     
    Create 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\n
     
    reStructuredText 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>`__\n
    "},{"location":"guide/markdown/#icons-images-and-figures","title":"Icons, Images and Figures","text":""},{"location":"guide/markdown/#icons","title":"Icons","text":"
    Material 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.\n
    "},{"location":"guide/markdown/#custom-icons","title":"Custom icons","text":"
    Custom icons:
     
     Empower everyone with open source geospatial
     
    Material for MkDocs provides support for custom icons:
     
    :osgeo-logo: Empower everyone with open source geospatial\n
     
    Add images to overrides/.icons/ (yes it is a hidden folder):
     
    overrides/\n- .icons/\n  - osgeo/\n    logo.svg\n
     
    reStructuredText 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\n
     
    Warning
     
    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\n
    "},{"location":"guide/markdown/#figures","title":"Figures","text":"
    Figures 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.
     
    ![FOSS4G](img/foss4g.svg)\n*Free and Open Source Software for Geospatial*\n
     
    Note
     
    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}\n
     
    Note
     
    The official Material for MkDocs answer for images with captions is to use md_in_html extension:
     
    <figure markdown=\"span\">\n  ![FOSS4G](img/foss4g.svg){ scale=\"25%\" }\n  <figcaption>Free and Open Source Software for Geospatial</figcaption>\n</figure>\n
     
    reStructuredText has a figure directive:
     
    .. code-block:: raw_markdown\n\n   ![](img/foss4g.svg)\n   *Free and Open Source Software for Geospatial*\n
    "},{"location":"guide/markdown/#images","title":"Images","text":"
    Image content:
     
     
    Markdown provides inline image syntax.
     
    ![](img/foss4g.svg)\n
     
    Use of mkdocs att_list can be used to adjust scale:
     
    ![](img/foss4g.svg){ scale=\"25%\" }\n
     
    reStructuredText has an image directive:
     
    .. image:: img/foss4g.svg\n   :scale: 25%\n
    "},{"location":"guide/markdown/#tables","title":"Tables","text":"
    Material 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 |\n
     
    Column alignment using :
     
    | First Header | Second Header | Third Header |\n|:-------------|:-------------:|-------------:|\n| Left         |    Center     |        Right |\n| Left         |    Center     |        Right |\n
    "},{"location":"guide/markdown/#inline-content","title":"Inline content","text":"
    Use 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\n
     
    The 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
     
       
    • mkdocs-include-markdown-plugin
      •  
    • mkdocs-exclude
      •  
    "},{"location":"guide/markdown/#include-content","title":"include content","text":"
    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/}\n
     
    Note
     
    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\n
     
    Note
     
    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'\n
    "},{"location":"guide/markdown/#include-config-and-code","title":"include config and code","text":"
    Including configuration and code examples:
     
    <CharacterString>da165110-88fd-11da-a88f-000d939bc5d8</CharacterString>\n
     
    Use 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```\n
     
    Note
     
    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:\n
    "},{"location":"guide/style/","title":"Style Guide","text":"
    Writing style guide to help creating consistent documentation.
     
    This style guide is useful as a reference when reviewing pull-requests for documentation.
     
    Reference
     
       
    • GeoServer Style Guide
      •  
    • GeoNetwork Style Guide
      •  
    "},{"location":"guide/style/#content-conventions","title":"Content conventions","text":""},{"location":"guide/style/#be-concise","title":"Be concise","text":"
    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
     
       
    1. Next, fire up whatever tool you use to browse the web and point it in the direction of ...
      2.  
     
    Good
     
       
    1. Next, start your web browser and navigate to ...
      2.  
    "},{"location":"guide/style/#use-direct-commands","title":"Use direct commands","text":"
    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
     
       
    1. Select a record by ...
      2.  
    "},{"location":"guide/style/#naming-conventions","title":"Naming conventions","text":"
    Reference
     
       
    • Wikipedia naming conventions
      •  
    "},{"location":"guide/style/#capitalization-of-page-names","title":"Capitalization of page names","text":"
    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}\n
     
    When 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\"/>\n
     
    For shell scripts, new lines can be escaped with a backslash character ([]{.title-ref}).
     
    mvn clean install \\\n    -DskipTests\n
     
    BUILD SUCCESS\n
     
    It 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.
     
       
    1.  
      To install development version use:
       
      pip install git+https://github.com/jodygarnett/translate.git\n
       
      2.  
    2.  
      Install script requirements, and check it runs:
       
      mkdocs_translate --help\n
       
      3.  
    3.  
      This script requires pandoc be installed:
       
      Ubuntu:
       
      apt-get install pandoc\n
       
      macOS:
       
      brew install pandoc\n
       
      Reference
       
         
      • https://pandoc.org/installing.html
        •  
       
      4.  
    "},{"location":"setup/#setup","title":"Project setup","text":"
       
    1.  
      A working example is provided to be adapted for your project.
       
      2.  
    2.  
      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\n
       
      3.  
    3.  
      Create 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 &copy; 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\n
       
      4.  
    4.  
      Create build/ folder for temporary files during migration.
       
      mkdir build\n
       
      Note
       
      If converting a maven project use of the existing target/ folder can be configured below.
       
      5.  
    5.  
      Define .gitingore to avoid adding generated artifacts to version control.
       
      __pycache__\ntarget\nbuild\n!.gitignore\n
       
      6.  
    6.  
      The resulting directory structure is:
       
      docs/\nsource/\n.gitignore\ndownload.py\nmkdocs.yml\nrequirements.txt\n
       
      7.  
    "},{"location":"setup/#download_hook","title":"Download Hook","text":"
    Optional: If your content uses downloaddirective to include external content, there is a mkdocshook for processing of download.txtfiles.
     
       
    1.  
      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\")\n
       
      2.  
    2.  
      Register hook with mkdocs.yml
       
      # Customizations\nhooks:\n- download.py\n
       
      Note
       
      See writing guide Download of external file for example on how to use this hook.
       
      3.  
    3.  
      The resulting directory structure is:
       
      docs/\nsource/\ndownload.py\nmkdocs.yml\nrequirements.txt\n
       
      4.  
    "},{"location":"setup/#config","title":"Configuration","text":"
    For simple python sphinx-build setup and directory structure no configuration is required.
     
    Optional: To provide configuration for your project:
     
       
    1.  
      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\nnav:\n  index.md: Home\n  'translate/index.md': Translate\n  'translate/migrate.md': Migrate\n  guide/index.md: Guide\n\n# markdown internationalization\ndeepl_base_url: \"https://api-free.deepl.com\"\nupload_folder: \"upload\"\ndownload_folder: \"download\"\n
       
      Note
       
      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.
       
      2.  
    2.  
      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\"\n
       
      3.  
    3.  
      The resulting directory structure is:
       
      docs/\nsource/\n.gitignore\ntranslate.yml\nmkdocs.yml\nrequirements.txt\n
       
      4.  
     
    The 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\n
     
    The 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'\n
     extlinks 
    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\n
     
    Note
     
    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}\n
     macro_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.
     nav 
    Provide simplified title for navigation, incase toctree title is too long. Most often used to override top-level index.rst title as \"Home\".
    "},{"location":"translate/","title":"Translate Script","text":"
    The translate script is used for migrating contents to mkdocs, and translating mkdocs content between languages.
     
       
    • Migrate to MkDocs
      •  
    • Language
      •  
    "},{"location":"translate/language/","title":"Language Internationalization","text":"
    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\n
     
    The 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\n
    "},{"location":"translate/language/#translate","title":"Language Translation","text":"
    Translation uses pandoc to convert to html and then using Deepl REST API.
     
       
    1.  
      Provide environmental variable with Deepl authentication key:
       
      export DEEPL_AUTH=\"xxxxxxxx-xxx-...-xxxxx:fx\"\n
       
      2.  
    2.  
      Translate a document to french using pandoc and deepl:
       
      mkdocs_translate french docs/help/index.md\n
       
      3.  
    3.  
      To translate several documents in a folder:
       
      mkdocs_translate french docs/overview/*.md\n
       
      4.  
    4.  
      See mkdocs_translate french --help for more options.
       
      5.  
    "},{"location":"translate/language/#limitations","title":"Limitations","text":"
    Keep in mind the following limitations:
     
       
    • Deepl charges by the character so bulk translation not advisable.
      •  
    • You are welcome to use google translate, ChatGPT, or Deepl directly - keeping in mind markdown formatting may be lost.
      •  
    • Please see the writing guide for what mkdocs functionality is supported.
      •  
     
    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_divs 
    The 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 from sphinx-build to mkdocs","text":""},{"location":"translate/migrate/#preflight","title":"Preflight","text":"
       
    1.  
      Use init to create docs directory and copy over non rst files (such as images and sample data).
       
      mkdocs_translate init\n
       
      2.  
    2.  
      To effectively migrate content the sphinx-build rst docs are scanned to collect information about the anchors, headings and downloads.
       
      mkdocs_translate scan\n
       
      3.  
    3.  
      The following is produced during preflight scans:
       
      build/migrate/anchors.txt\ndocs/download/download.txt\ndocs/guide/download/download.txt\ndocs/setup/download/download.txt\n
       
      4.  
     
    Troubleshooting:
     
       
    •  
      You can run these scans independently:
       
      mkdocs_translate scan --scan=download\nmkdocs_translate scan --scan=index\n
       
      •  
    •  
      To troubleshoot an individual file, the resulting indexcan be sent to standard out:
       
      mkdocs_translate scan source/setup/index.rst\nmkdocs_translate scan --scan=download source/setup/index.rst\nmkdocs_translate scan --scan=index source/setup/index.rst\n
       
      •  
    "},{"location":"translate/migrate/#navigation","title":"Navigation","text":"
       
    1.  
      To generate out navigation tree:
       
      mkdocs_translate scan toc\n
       
      2.  
     
    2. The output is printed to standard out and may be appended to mkdocs.yml file.
     
    {% \n  include \"../../mkdocs.yml\"\n   start=\"# Page tree\"\n%}\n
    "},{"location":"translate/migrate/#migrate","title":"Content Migration","text":"
    Format conversion from sphinx-build reStructuredText files to mkdocs Markdown content.
     
       
    1.  
      To bulk convert all content from rst to md:
       
      mkdocs_translate migrate\n
       
      2.  
    2.  
      Review this content you may find individual files to fix.
       
      Some formatting is easier to fix in the rst files before conversion:
       
         
      • Indention of nested lists in rst content is often incorrect, resulting in restarted numbering or block quotes.
        •  
      • Random {.title-ref} snippets is a general indication to simplify the rst and re-translate.
        •  
      • Anchors or headings with trailing whitespace throwing off the heading scan, resulting in broken references
        •  
       
      3.  
     
    Troubleshooting:
     
       
    •  
      Convert a single file:
       
      mkdocs_translate migrate source/introduction/license.rst\n
       
      •  
    •  
      Bulk convert files in a folder:
       
      mkdocs_translate migrate source/introduction/**/*.rst\n
       
      •  
    "},{"location":"translate/migrate/#known-limitations","title":"Known limitations","text":"
    Some 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
       
      •  
    "}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"MkDocs Translate","text":"
    Translation example for mkdocs_translate script Release 0.9.
     
       
    • Getting started
      •  
    • Translate Script
      •  
    • Writing Guide
      •  
    • Development
      •  
     
    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:
     
       
    1.  
      Clone:
       
      git clone https://github.com/jodygarnett/translate.git translate\n
       
      2.  
    2.  
      Install requirements:
       
      cd translate\npip3 install -r mkdocs_translate/requirements.txt\n
       
      3.  
    3.  
      Install locally:
       
      pip3 install -e .\n
       
      4.  
    "},{"location":"development/#debugging","title":"Debugging","text":"
       
    1.  
      Recommend troubleshooting a single file at a time:
       
      mkdocs_translate migrate source/index.rst\n
       
      2.  
    2.  
      Compare the temporary files staged for pandoc conversion:
       
      bbedit source/index.rst docs/index.md build/migrate/index.tmp.html build/migrate/index.tmp.md\n
       
      3.  
    3.  
      To turn on logging during migrating a file:
       
      mkdocs_translate --log=DEBUG migrate source/index.rst\n
       
      4.  
    4.  
      To troubleshoot indexing when scanning a single document:
       
      mkdocs_translate --log=DEBUG scan index --TEST source/index.rst\n
       
      The index information is sent to standard out (rather than added to a anchor.txt file.
       
      5.  
    5.  
      To troubleshoot downloads when scanning a single document:
       
      mkdocs_translate --log=DEBUG scan download --TEST source/index.rst\n
       
      The download information is sent to standard out (rather than a download.txt file.
       
      6.  
    "},{"location":"development/#pandoc","title":"Pandoc","text":"
       
    1.  
      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'\n
       
      2.  
    2.  
      The 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 processing 
      3.  
    3.  
      Language 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\n
       
      Langauge conversion uses text/html to avoid internationalization of content distributing markdown formatting.
       
      4.  
    "},{"location":"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":"guide/","title":"Writing Guide","text":"
    Working with documentation, markdown formatting, and writing style guide.
     
       
    • Markdown
      •  
    • 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 selection monospace 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.\n
     
    Rich structured text uses menuselection and guilabel directives:
     
    Navigate to **Data --> Layers** page,\nand press **Add** to create a new layer.\n
    "},{"location":"guide/markdown/#selected-input","title":"Selected input","text":"
    Use item for user selected input, or item in a list or tree:
     
    Preview:
     
    Select Basemap layer.
     
    Markdown uses monospace:
     
    Select `Basemap` layer.\n
     
    Rich structured text uses monospace:
     
    Select ``Basemap`` layer.\n
    "},{"location":"guide/markdown/#input-text","title":"Input text","text":"
    Use monospace for user supplied text input:
     
    Preview:
     
    Use the Search field to enter: Ocean*
     
    Markdown uses monospace:
     
    Use the **Search** field enter: `Ocean*`\n
     
    Rich structured text uses kbd directive:
     
    Use the **Search** field to enter: ``Ocean*``\n
    "},{"location":"guide/markdown/#keypress","title":"Keypress","text":"
    Use key directive for keyboard keys.
     
    Preview:
     
    Press Control-s to search.
     
    Markdown uses mkdocs-material keys formatting:
     
    Press ++control+s++ to search.\n
     
    Rich structured text:
     
    Press `Control-s` to search.\n
    "},{"location":"guide/markdown/#form-input","title":"Form input","text":"
    Use 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:
     
       
    1.  
      To login as the GeoServer administrator using the default password:
       User: 
      admin
       Password: 
      geoserver
       Remember me 
      Unchecked
       
      Press Login.
       
      2.  
     
    Markdown: definition lists
     
    1.  To login as the GeoServer administrator using the default password:\n\n    **User**\n\n    :   `admin`\n\n\n    **Password**\n\n    :   `geoserver`\n\n\n    **Remember me**\n\n    :   Unchecked\n\n    Press **Login**.\n
     
    Rich 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`\n      * - Password:\n        - `geoserver`\n      * - Remember me\n        - Unchecked\n\n   Press **Login**.\n
    "},{"location":"guide/markdown/#applications-commands-and-tools","title":"Applications, commands and tools","text":"
    Use 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.\n
     
    Rich structured text uses command directive:
     
    Launch ***pgAdmin*** and connect to the ``tutorial`` database.\n
    "},{"location":"guide/markdown/#files","title":"Files","text":"
    Use 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\n
     
    Rich structured text:
     
    See configuration\nfile **`WEB-INF/config-security/config-security-ldap.xml`**\nfor details\n
    "},{"location":"guide/markdown/#links-and-references","title":"Links and references","text":""},{"location":"guide/markdown/#internal-references","title":"Internal References","text":"
    Reference 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.\n
     
    reStructuredText use of ref directive:
     
    Authors have access to `translation <../translate/language.rst#translate>`_ for initial draft.\n
    "},{"location":"guide/markdown/#download-of-sample-file","title":"Download of sample file","text":"
    Sample file included in the documentation:
     
    Download schema example.txt.
     
    Markdown relative link, with text following bold with monospace file convention above:
     
    Download text [**`example.txt`**](files/example.txt).\n
     
    You may also experiment with mkdocs attr_list to supply a filename:
     
    Download text [**`example.txt`**](files/example.txt) {:download=\"example.txt\"} .\n
     
    reStructured text uses downlaod directive:
     
    Download text `example.txt <files/example.txt>`__.\n
    "},{"location":"guide/markdown/#download_external","title":"Download of external file","text":"
    To 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)\n
     
    Create 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\n
     
    reStructuredText 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>`__\n
    "},{"location":"guide/markdown/#icons-images-and-figures","title":"Icons, Images and Figures","text":""},{"location":"guide/markdown/#icons","title":"Icons","text":"
    Material 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.\n
    "},{"location":"guide/markdown/#custom-icons","title":"Custom icons","text":"
    Custom icons:
     
     Empower everyone with open source geospatial
     
    Material for MkDocs provides support for custom icons:
     
    :osgeo-logo: Empower everyone with open source geospatial\n
     
    Add images to overrides/.icons/ (yes it is a hidden folder):
     
    overrides/\n- .icons/\n  - osgeo/\n    logo.svg\n
     
    reStructuredText 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\n
     
    Warning
     
    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\n
    "},{"location":"guide/markdown/#figures","title":"Figures","text":"
    Figures 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.
     
    ![FOSS4G](img/foss4g.svg)\n*Free and Open Source Software for Geospatial*\n
     
    Note
     
    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}\n
     
    Note
     
    The official Material for MkDocs answer for images with captions is to use md_in_html extension:
     
    <figure markdown=\"span\">\n  ![FOSS4G](img/foss4g.svg){ scale=\"25%\" }\n  <figcaption>Free and Open Source Software for Geospatial</figcaption>\n</figure>\n
     
    reStructuredText has a figure directive:
     
    .. code-block:: raw_markdown\n\n   ![](img/foss4g.svg)\n   *Free and Open Source Software for Geospatial*\n
    "},{"location":"guide/markdown/#images","title":"Images","text":"
    Image content:
     
     
    Markdown provides inline image syntax.
     
    ![](img/foss4g.svg)\n
     
    Use of mkdocs att_list can be used to adjust scale:
     
    ![](img/foss4g.svg){ scale=\"25%\" }\n
     
    reStructuredText has an image directive:
     
    .. image:: img/foss4g.svg\n   :scale: 25%\n
    "},{"location":"guide/markdown/#tables","title":"Tables","text":"
    Material 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 |\n
     
    Column alignment using :
     
    | First Header | Second Header | Third Header |\n|:-------------|:-------------:|-------------:|\n| Left         |    Center     |        Right |\n| Left         |    Center     |        Right |\n
    "},{"location":"guide/markdown/#inline-content","title":"Inline content","text":"
    Use 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\n
     
    The 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
     
       
    • mkdocs-include-markdown-plugin
      •  
    • mkdocs-exclude
      •  
    "},{"location":"guide/markdown/#include-content","title":"include content","text":"
    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/}\n
     
    Note
     
    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\n
     
    Note
     
    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'\n
    "},{"location":"guide/markdown/#include-config-and-code","title":"include config and code","text":"
    Including configuration and code examples:
     
    <CharacterString>da165110-88fd-11da-a88f-000d939bc5d8</CharacterString>\n
     
    Use include to 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```\n
     
    Note
     
    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:\n
    "},{"location":"guide/style/","title":"Style Guide","text":"
    Writing style guide to help creating consistent documentation.
     
    This style guide is useful as a reference when reviewing pull-requests for documentation.
     
    Reference
     
       
    • GeoServer Style Guide
      •  
    • GeoNetwork Style Guide
      •  
    "},{"location":"guide/style/#content-conventions","title":"Content conventions","text":""},{"location":"guide/style/#be-concise","title":"Be concise","text":"
    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
     
       
    1. Next, fire up whatever tool you use to browse the web and point it in the direction of ...
      2.  
     
    Good
     
       
    1. Next, start your web browser and navigate to ...
      2.  
    "},{"location":"guide/style/#use-direct-commands","title":"Use direct commands","text":"
    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
     
       
    1. Select a record by ...
      2.  
    "},{"location":"guide/style/#naming-conventions","title":"Naming conventions","text":"
    Reference
     
       
    • Wikipedia naming conventions
      •  
    "},{"location":"guide/style/#capitalization-of-page-names","title":"Capitalization of page names","text":"
    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}\n
     
    When 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\"/>\n
     
    For shell scripts, new lines can be escaped with a backslash character ([]{.title-ref}).
     
    mvn clean install \\\n    -DskipTests\n
     
    BUILD SUCCESS\n
     
    It 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.
     
       
    1.  
      To install development version use:
       
      pip install git+https://github.com/jodygarnett/translate.git\n
       
      2.  
    2.  
      Install script requirements, and check it runs:
       
      mkdocs_translate --help\n
       
      3.  
    3.  
      This script requires pandoc be installed:
       
      Ubuntu:
       
      apt-get install pandoc\n
       
      macOS:
       
      brew install pandoc\n
       
      Reference
       
         
      • https://pandoc.org/installing.html
        •  
       
      4.  
    "},{"location":"setup/#setup","title":"Project setup","text":"
       
    1.  
      A working example is provided to be adapted for your project.
       
      2.  
    2.  
      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\n
       
      3.  
    3.  
      Create 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 &copy; 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\n
       
      4.  
    4.  
      Create build/ folder for temporary files during migration.
       
      mkdir build\n
       
      Note
       
      If converting a maven project use of the existing target/ folder can be configured below.
       
      5.  
    5.  
      Define .gitingore to avoid adding generated artifacts to version control.
       
      __pycache__\ntarget\nbuild\n!.gitignore\n
       
      6.  
    6.  
      The resulting directory structure is:
       
      docs/\nsource/\n.gitignore\ndownload.py\nmkdocs.yml\nrequirements.txt\n
       
      7.  
    "},{"location":"setup/#download_hook","title":"Download Hook","text":"
    Optional: If your content uses download directive to include external content, there is a mkdocs hook for processing of download.txt files.
     
       
    1.  
      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\")\n
       
      2.  
    2.  
      Register hook with mkdocs.yml:
       
      # Customizations\nhooks:\n- download.py\n
       
      Note
       
      See writing guide Download of external file for example on how to use this hook.
       
      3.  
    3.  
      The resulting directory structure is:
       
      docs/\nsource/\ndownload.py\nmkdocs.yml\nrequirements.txt\n
       
      4.  
    "},{"location":"setup/#config","title":"Configuration","text":"
    For simple python sphinx-build setup and directory structure no configuration is required.
     
    Optional: To provide configuration for your project:
     
       
    1.  
      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\nnav:\n  index.md: Home\n  'translate/index.md': Translate\n  'translate/migrate.md': Migrate\n  guide/index.md: Guide\n\n# markdown internationalization\ndeepl_base_url: \"https://api-free.deepl.com\"\nupload_folder: \"upload\"\ndownload_folder: \"download\"\n
       
      Note
       
      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.
       
      2.  
    2.  
      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\"\n
       
      3.  
    3.  
      The resulting directory structure is:
       
      docs/\nsource/\n.gitignore\ntranslate.yml\nmkdocs.yml\nrequirements.txt\n
       
      4.  
     
    The 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\n
     
    The built-in substitutions for {{ version }} and {{ release }} are changed to {{ version }} and {{ release }} variables for use with mkdocs-macros-plugin variable substitution:
     
    Use mkdocs.yml to define these variable substitutions:
     
    extra:\n  homepage: https://geoserver.org/\n  version: '2.24'\n  release: '2.24.2'\n
     extlinks: 
    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\n
     
    Note
     
    Use of mkdocs-macros-plugin for variable substitution of release above.
     
    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}\n
     macro_ignore: 
    Use of mkdocs-macros-plugin can 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.
     nav: 
    Provide simplified title for navigation, incase toctree title is too long. Most often used to override top-level index.rst title as \"Home\".
    "},{"location":"translate/","title":"Translate Script","text":"
    The translate script is used for migrating contents to mkdocs, and translating mkdocs content between languages.
     
       
    • Migrate to MkDocs
      •  
    • Language
      •  
    "},{"location":"translate/language/","title":"Language Internationalization","text":"
    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\n
     
    The 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\n
    "},{"location":"translate/language/#translate","title":"Language Translation","text":"
    Translation uses pandoc to convert to html, and then using Deepl REST API.
     
       
    1.  
      Provide environmental variable with Deepl authentication key:
       
      export DEEPL_AUTH=\"xxxxxxxx-xxx-...-xxxxx:fx\"\n
       
      2.  
    2.  
      Translate a document to french using pandoc and deepl:
       
      mkdocs_translate french docs/help/index.md\n
       
      3.  
    3.  
      To translate several documents in a folder:
       
      mkdocs_translate french docs/overview/*.md\n
       
      4.  
    4.  
      See mkdocs_translate french --help for more options.
       
      5.  
    "},{"location":"translate/language/#limitations","title":"Limitations","text":"
    Keep in mind the following limitations:
     
       
    • Deepl charges by the character so bulk translation not advisable.
      •  
    • You are welcome to use google translate, ChatGPT, or Deepl directly - keeping in mind markdown formatting may be lost.
      •  
    • Please see the writing guide for what mkdocs functionality is supported.
      •  
     
    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_divs 
    The 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 from sphinx-build to mkdocs","text":""},{"location":"translate/migrate/#preflight","title":"Preflight","text":"
       
    1.  
      Use init to create docs directory and copy over non rst files (such as images and sample data).
       
      mkdocs_translate init\n
       
      2.  
    2.  
      To effectively migrate content the sphinx-build rst docs are scanned to collect information about the anchors, headings and downloads.
       
      mkdocs_translate scan\n
       
      3.  
    3.  
      The following is produced during preflight scans:
       
      build/migrate/anchors.txt\ndocs/download/download.txt\ndocs/guide/download/download.txt\ndocs/setup/download/download.txt\n
       
      4.  
     
    Troubleshooting:
     
       
    •  
      You can run these scans independently:
       
      mkdocs_translate scan --scan=download\nmkdocs_translate scan --scan=index\n
       
      •  
    •  
      To troubleshoot an individual file, the resulting index can be sent to standard out:
       
      mkdocs_translate scan source/setup/index.rst\nmkdocs_translate scan --scan=download source/setup/index.rst\nmkdocs_translate scan --scan=index source/setup/index.rst\n
       
      •  
    "},{"location":"translate/migrate/#navigation","title":"Navigation","text":"
       
    1.  
      To generate out navigation tree:
       
      mkdocs_translate scan toc\n
       
      2.  
     
    2. The output is printed to standard out and may be appended to mkdocs.yml file.
     
    {% \n  include \"../../mkdocs.yml\"\n   start=\"# Page tree\"\n%}\n
    "},{"location":"translate/migrate/#migrate","title":"Content Migration","text":"
    Format conversion from sphinx-build reStructuredText files to mkdocs Markdown content.
     
       
    1.  
      To bulk convert all content from rst to md:
       
      mkdocs_translate migrate\n
       
      2.  
    2.  
      Review this content you may find individual files to fix.
       
      Some formatting is easier to fix in the rst files before conversion:
       
         
      • Indention of nested lists in rst content is often incorrect, resulting in restarted numbering or block quotes.
        •  
      • Random {.title-ref} snippets is a general indication to simplify the rst and re-translate.
        •  
      • Anchors or headings with trailing whitespace throwing off the heading scan, resulting in broken references
        •  
       
      3.  
     
    Troubleshooting:
     
       
    •  
      Convert a single file:
       
      mkdocs_translate migrate source/introduction/license.rst\n
       
      •  
    •  
      Bulk convert files in a folder:
       
      mkdocs_translate migrate source/introduction/**/*.rst\n
       
      •  
    "},{"location":"translate/migrate/#known-limitations","title":"Known limitations","text":"
    Some 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
       
      •  
    "}]}
\ No newline at end of file
diff --git a/setup/index.html b/setup/index.html
index 56b20ab..02af49f 100644
--- a/setup/index.html
+++ b/setup/index.html
@@ -782,7 +782,7 @@ 
    Project setup
    
 
 
 
    Download Hook
    
-
    Optional: If your content uses downloaddirective to include external content, there is a mkdocshook for processing of download.txtfiles.
    
+
    Optional: If your content uses download directive to include external content, there is a mkdocs hook for processing of download.txt files.
    
 
      
 
    1. 
 
      Create download.py.
      
@@ -825,7 +825,7 @@ 
      Download Hook
      
 

 
 
  • 
-
    Register hook with mkdocs.yml
    
+
    Register hook with mkdocs.yml:
    
 
    # Customizations
 hooks:
 - download.py
@@ -922,27 +922,27 @@ 
    Configuration
    
 
    
 
    Default assumes you are running from the current directory.
    
 
    
-
    docs_folder docs
    
+
    docs_folder: docs
    
 
    
 
    mkdocs convention.
    
 
    
-
    build_folder build
    
+
    build_folder: build
    
 
    
 
    The use of build follows sphinx-build and mkdocs convention, maven projects may wish to use target.
    
 
    
-
    rst_folder source
    
+
    rst_folder: source
    
 
    
 
    Location of sphinx-build documentation to migrate to mkdocs.
    
 
    
-
    anchor_file anchors.txt
    
+
    anchor_file: anchors.txt
    
 
    
 
    Name of index file used to lookup anchor and title information during migration.
    
 
    
-
    convert_folder migrate
    
+
    convert_folder: migrate
    
 
    
-
    Combined with build_folder for rst conversion temporary files (example: build/migrate. Temporary files are required for use by pandoc.
    
+
    Combined with build_folder for rst conversion temporary files (example: build/migrate). Temporary files are required for use by pandoc.
    
 
    
-
    upload_folder upload
    
+
    upload_folder: upload
    
 
    
 
    Combined with build_folder to stage html files for internationalization (example: build/upload)
    
 
    
@@ -950,19 +950,19 @@ 
    Configuration
    
 
    
 
    Customize if you have a subscription to deepl.
    
 
    
-
    download_folder download
    
+
    download_folder: download
    
 
    
 
    Combined with build_folder to retrieve internationalization results (example: build/download) Temporary files are required for use by pandoc.
    
 
    
-
    substitutions
    
+
    substitutions:
    
 
    
-
    dictionary of |substitutions|to use when converting config.py rst_epilog common substitutions.
    
+
    dictionary of |substitutions| to use when converting config.py rst_epilog common substitutions.
    
 
    project: GeoServer
 author: Open Source Geospatial Foundation
 copyright: 2023, Open Source Geospatial Foundation
 project_copyright: 2023, Open Source Geospatial Foundation
 
    
-
    The built-in substitutions for {{ version }}and {{ release }}are changed to {{ version }} and {{ release }} variables for use with mkdocs-macros-pluginvariable substitution:
    
+
    The built-in substitutions for {{ version }} and {{ release }} are changed to {{ version }} and {{ release }} variables for use with mkdocs-macros-plugin variable substitution:
    
 
    Use mkdocs.yml to define these variable substitutions:
    
 
    extra:
   homepage: https://geoserver.org/
@@ -970,7 +970,7 @@ 
    Configuration
    
       release: '2.24.2'
 
    
 
    
-
    extlinks
    
+
    extlinks:
    
 
    
 
    dictionary of config.py extlinks substitutions taking the form:
    
 
    extlinks:
@@ -981,7 +981,7 @@ 
    Configuration
    
 
    
 
    
 
    Note
    
-
    Use of mkdocs-macros-pluginfor variable substitution of releaseabove.
    
+
    Use of mkdocs-macros-plugin for variable substitution of release above.
    
 
    Use of |GEOS-%s to override default link text %s.
    
 
    
 
    This handles the sphinx-build config.py extlinks during migration:
    
@@ -993,12 +993,12 @@ 
    Configuration
    
 }
 
    
 
-
    macro_ignore
    
+
    macro_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.
    
+
    Use of mkdocs-macros-plugin can 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.
    
 
    
-
    nav
    
+
    nav:
    
 
    
 
    Provide simplified title for navigation, incase toctree title is too long. Most often used to override top-level index.rst title as "Home".
    
 
    
diff --git a/sitemap.xml b/sitemap.xml
index 6c7a589..858faf4 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,57 +2,57 @@
 
     
          http://jodygarnett.github.io/translate/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/development/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/download/LICENSE/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/guide/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/guide/markdown/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/guide/style/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/guide/download/LICENSE/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/setup/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/translate/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/translate/language/
-         2024-02-22
+         2024-02-23
          daily
     
     
          http://jodygarnett.github.io/translate/translate/migrate/
-         2024-02-22
+         2024-02-23
          daily
     
 
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index bed099a31bbd815eefde586d935872d74cd30f8f..17961add1a25fa60355322c831dfd6c70e700410 100644
GIT binary patch
literal 295
zcmV+?0oeW@iwFqt4B2G@|8r?{Wo=<_E_iKh0M(SwPQx$^#_xNID)%O(Z~)Y12Q(xk
z#07YO(0FMee@f!6^zBKv3U)_AtuL{yFQ0z0ELYnvYqA4`sJ*Mn1uaMhuJKYkRg>43
z`}~@0`KIcFiGW!WyI7MJvAbn#7zP?Of)!n)J}4HOHWiW0O;*qw!Z%rp$>5Y7qcXnX
zv&*}eqY}XZB2^mO{*7wSFbEfoKwuS{#OHrSMC&Cli}ETj%DlWxlDT&#Yg*wH>;rsq
zDYO|YcGfvTu^*~G@JTp;@tp;S%V+h2GhRsc_;9y-dfqJ_SoK=MN+_)eAJc$Wf*Wx(
tYZ>k8_BI{MzFR!ydXDUGW|Dm`)S8g3R^eZUe00onc^iwFqX|JG#!|8r?{Wo=<_E_iKh0M(SwO2jY_#_#(SCHFS9cu;Ax2U$T7
zFX{utW=x~`Q~AO?$FT?s!SFs5&Py8FE*60z--aLFV
z!IhqBy6T*v=nvH&_yin5yWW7s?X$YkYR3hAxW7F-J{>j>EC(eZ5lX}T$2{Ofa05;{
smC+`*xA9mG{pKmtIkLZ*j`jnWDIpsr{l5(P^u*O;-ykpeYS#w<0ANOsHvj+t

diff --git a/translate/language/index.html b/translate/language/index.html
index 907a863..927cb83 100644
--- a/translate/language/index.html
+++ b/translate/language/index.html
@@ -637,7 +637,7 @@
 
    Language Internationalization
    
 
    To help manage a multi-language build is it kind to provide human translators with an example document to start from.
    
 
    Setup
    
-
    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:
    
+
    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
 | index.fr.md
 + img/
@@ -661,7 +661,7 @@ 
    Setup
    
             Search: Recherche
 
    
 
    Language Translation
    
-
    Translation uses pandoc to convert to html and then using Deepl REST API.
    
+
    Translation uses pandoc to convert to html, and then using Deepl REST API.
    
 
      
 
    1. 
 
      Provide environmental variable with Deepl authentication key:
      
diff --git a/translate/migrate/index.html b/translate/migrate/index.html
index 8016e5c..7645739 100644
--- a/translate/migrate/index.html
+++ b/translate/migrate/index.html
@@ -671,7 +671,7 @@ 
      Preflight
      
 
    • 
 
 
  • 
-
    To troubleshoot an individual file, the resulting indexcan be sent to standard out:
    
+
    To troubleshoot an individual file, the resulting index can be sent to standard out:
    
 
    mkdocs_translate scan source/setup/index.rst
 mkdocs_translate scan --scan=download source/setup/index.rst
 mkdocs_translate scan --scan=index source/setup/index.rst