Change from sphinx-build and reStructuredText to mkdocs and MarkDown.

• mkdocs build is faster, and responsive when editing with a live preview

• the search actually works, and there is a version switcher

• material-for-mkdocs theme is very good and well supported

• Pros: Some of the advanced features we enjoy like literal-include are covered by markdown extensions

• Cons: We give up some explicit features (guilabel, menuselection, file, download) so we will need clear writing guidelines for consistency

• Compare geoserver: sphinx-build vs mkdocs preview

• Compare geonetwork: sphinx-build vs mkdocs which uses version selector for older content.

Jody Garnett (geocat.net)

Krishna Lodha (rottengrapes.tech)

This proposal is for all active branches (GeoServer 2.25, 2.24.x, 2.23.x).

• Under Discussion
• In Progress
• Completed
• Rejected
• Deferred

The complexity of sphinx-build is cited as a difficulty of working with GeoServer documentation. Truthfully we have used many advanced features of sphinx-build over the years making our documentation complicated.

By changing to Markdown this proposal aims to lower the barrier of participation.

Change from sphinx-build and reStructuredText to mkdocs and MarkDown.

• Convert content only during migration, no rewrites at the same time (painful lesson from confluence to sphinx-build migration)

• Convert only using a script, no editing by hand. in order to update all active branches:

  • See http://github.com/jodygarnett/translate
  • The script uses pandoc and then cleans up the mess for any sphinx-build directives that pandoc cannot support
  • Indexes rst content into anchors.txt file, in oder to process doc, ref and toctree directives In general script needs to handle sphinx-build directives that require knowledge of documentation structure beyond a single file.
  • With this approach it is faster to fix common problems in RST and re-convert (example for unexpected block quotes due to indenting)

• The structure is similar, with an mkdocs.yml providing settings and a navigation tree of pages

  /docs/en/user/docs/index.md
  /docs/en/user/mkdocs.yml
  /docs/en/build.xml
  /docs/en/requirements.txt
  

  mkdocs is a python build system, so the existing nightly builds and workflow will remain the same

This is a breaking change to the documentation build system.

To mitigate the effects of this change the proposal is to update all active branches at the same time.

Q: Do we do all active branches?

Yes we can do that, it will require a documentation freeze for 1-2 days to convert the content.

Q: Can we use a the version selector?

The version selector is provided by mike which is a tool to publish to GitHub pages; but we may be able to mirror the same directory structure:

• versions.json
• 2.25/
• latest/
• 2.24/
• stable/
• 2.23/
• maintenance/

Q: Can we have a preview?

I would prefer to get agreement before sinking a lot of time into the migration process.

Here is a preview thus far: sphinx-build vs mkdocs preview

Q: Can the theme integrate better with geoserver.org website

Yes, but we should keep in mind light and dark mode functionality.

See the preview above for the improvement based on this question.

Q: Markdown limitations?

1. The sphinx-build system supported had inline-directives which have no markdown equivalent. These will need to be addressed with a writing guide.

   Markdown	Directive
   **strong**	gui label, menu selection
   `monospace`	text input, item selection
   *emphasis*	figure (caption)
   ***strong-emphasis***	application, command
   monospace-strong	file

   The above mapping are baked into the translation script use for content conversion.

   Here is writing guide provided to core-geonetwork project: Markdown (GeoNetwork Developer Guide)

2. Substiutions are not supported in markdown, the mkdocs-macros-plugin can be used

   docker run -it -p8080:8080 docker.osgeo.org/geoserver:{{ release }}
   

   There are mkdocs extensions that could perform similar functions but seem complicated.

   Having working cut and paste examples to use really help step by step instructions so this is an important story to address.

3. We had very complicated sphinx-build conf.py logic to dynamically construct external link references (for providing download links). This has no markdown equivalent.

   Download the extension here - :download_extension:`geopkg-output`
   

   Here an example of recreating this with the macro plugin:

   https://sourceforge.net/projects/geoserver/files/GeoServer/{{ release }}/geoserver-{{ release }}-%s.zip|geoserver-{{ release }}-%s.zip
   

4. Directives that made linking between documentation pages easy will need to be handled by relative links.

   For directives like :doc:<install_linux> will need to be [Linux installation instructions](../../install/linux/index.md).

   During conversion the relative paths and link text is handled, but going forward you will need to take the simple markdown approach.

5. Use of content pre-process functionality to selectively include ..only snapshot or .. only release has no markdown equivalent.

   Conversion will include such blocks as a note for now.

   3.  Run the container
   
       !!! abstract "Release"
   
           ``` text
           docker run -it -p8080:8080 docker.osgeo.org/geoserver:2.25-RC
           ```
   
       !!! abstract "Nightly Build"
   
           ``` text
           docker run -it -p8080:8080 docker.osgeo.org/geoserver:2.25.x
           ```

   This occurs a lot during installation instructions. I suggest we rewrite to use content tabs to provide instructions for the release, and instructions for the nightly build.

   3.  Run the container
   
       === "Release"
   
           ``` text
           docker run -it -p8080:8080 docker.osgeo.org/geoserver:2.25-RC
           ```
   
       === "Nightly Build"
   
           ``` text
           docker run -it -p8080:8080 docker.osgeo.org/geoserver:2.25.x
           ```

6. Downloads are important to ensure docs use examples form the codebase.

   I updated the script to produce download/download.txt file for when a download referenced a file from the codebase.

   I added an mkdocs build hook, that search for download.txt files and copy the files if required.

   The use of download/.gitignore recommended to prevent content being duplicated.

   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/GEOSERVER_DEVELOPER_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/IMPORTER_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/VERBOSE_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/PRODUCTION_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/QUIET_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/GEOTOOLS_DEVELOPER_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/configuration/download/DEFAULT_LOGGING.xml
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/introduction/download/NOTICE.md
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/introduction/download/apache-2.0.md
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/introduction/download/GPL.md
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/introduction/download/apache-1.1.md
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/introduction/download/epl-1.0.md
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/collection.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/functions.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/collection_include.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/landingPage.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/getfeature-empty.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/getfeature-header.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/queryables.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/collections.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/getfeature-content.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/getfeature-complex-content.ftl
   Download /Users/jgarnett/dev/geoserver/geoserver/doc/en/user/docs/community/ogc-api/features/download/getfeature-footer.ftl
   

Project Steering Committee:

• Alessio Fabiani: +1
• Andrea Aime: +1
• Ian Turton: +1
• Jody Garnett: +1 (initial motion)
• Jukka Rahkonen:
• Kevin Smith:
• Simone Giannecchini:
• Torben Barsballe: +1
• Nuno Oliveira:

Community support:

• Krishna Lodha +1 (initial motion)
• Peter Smythe +1)

• https://osgeo-org.atlassian.net/browse/GEOS-11221
• https://github.com/geoserver/geoserver/pull/7429
• https://github.com/geoserver/geoserver/tree/mkdocs/doc/en/user
• https://github.com/geotools/geotools/wiki/MkDocs