Migration to MkDocs #453
Draft
Migration to MkDocs #453
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
In apache/pinot#17281, I proposed migrating the documentation from GitBook to MkDocs.
Important
This PR is intended to be an example of how to migrate the doc content from GitBook to MkDocs, but it is not complete and even if it were, merging this PR would mean GitBook would stop working. Please do not merge this PR
Description
This PR shows how to do that. All pages can currently be rendered with MkDocs, but some proprietary GitBook extensions need to be migrated to the Material for MkDocs syntax. I included a
copilot-instructionfile that helps with the migration and can also be used as a comprehensive list of the changes I found we need to apply.The following files have been migrated:
To serve docs locally, you can run:
poetry run mkdocs serve --livereload`By doing so, you will get a long list of warnings. Most of them say that some link is broken. Most (if not all) are showing cases where the current documentation link is incorrectly written. As explained in the Pinot issue, one of the main advantages of moving to MkDocs is that, once we fix all current broken links, we can add a GHA check that prevents PRs from being merged if they introduce broken links.
As an example, when migrating
basics/components/cluster/broker.md, I saw the following error message in the log:The problem here is that the file is called
broker-time-boundary-diagram.jpg.jpgwhile the file on disk is calledbroker-time-boundary-diagram.jpg. Although this is just a warning, if mkdocs is served in strict mode, the process fails in cases like this. By compiling the docs in this mode in GHA we can prevent this erros to happen in the future