Refactor Version and Language handling.
What is the proposal?
Our next target version for mkdocs-material
is 7.0.0 which brings native language handling to mkdocs-material. We could use this to allow single-repository setups for multi-language documentation books which has been requested
This would result in the following changes in behaviour:
- All link patterns would change for example from: https://docs.civicrm.org/user/en/latest to https://docs.civicrm.org/user/ (with
en
and any versions being handled bymkdocs-material
itself) - Any currently multilingual documentation book will need to refactor to organise documentation according to the new structure moving files from
/docs/
to/docs/<lang>
and centralising into a single repository.
Why would we do this?
This would shift maintenance burden from docs-publisher
to mkdocs-material
and allow for docs-publisher
agnostic handling of versioning and language handling, allow for all documentation to live alongside code which is a desirable pattern and drastically simplify the docs-publisher
codebase.
What changes will actually take place?
Any translated extension book or core book repository will be merged into the main repository for the extension/book and the translation repo will be archived. The structure for the User Guide would look like this in the main user guide repository.
/docs/en/
/docs/fr/
/docs/de/
/docs/es/
/docs/ca/
What do we need to proceed?
Robust discussion of the proposed changes in behaviour and some sense of consensus that this would be desirable. Particular emphasis will be given to the opinions of those who maintain multilingual documentation books or copies of books.
Questions / concerns answered
Impact of URL changes on SEO/search indexing: Permanent redirect from old URL styles to new will be handled by docs-publisher
.