There are a million good reasons to start writing documentation. Documentation is the key to preserving acquired knowledge indefinitely - for others and for your future self (who might be quite different if things are going well). As essential tool as documentation must promote the idea of keeping it up-to-date by ensuring easy access to editing pages, so that including more details to existing information and putting focus on right things is simple.
While some documentation management systems like Confluence, Notion and others allow in-place content editing, systems with serialisable content stored separately, such as MkDocs, it's not that straightforward. In this article, we will discuss MkDocs that offers an out-of-the-box solution for that.
MkDocs has the ability to enhance pages with an "Edit" button that allows opening the source code of a specific page in Git repository. However, most guides (including official documentation) focus on scenarios involving cloud-based Git repositories. That's a quite cool feature, especially, if documentation maintenance is public but that's not as helpful for maintainers working on pages locally.
In this material, let's explore how to make "Edit" button open pages in modern IDEs using custom URI schemes, allowing for a seamless transition from viewing to editing.
Vision
The objective is simple: equip every page in a MkDocs Material generated documentation site with an "Edit" button that opens the corresponding source markdown file in VS Code.
Solution
-
Understanding the Configuration: Familiarise yourself with the
edit_uri
configuration option in the MkDocs documentation. - Unveiling VS Code's Power: Explore the documentation on launching VS Code using custom URLs. This knowledge will empower our "Edit" button to spring into action.
-
Crafting the Base URL: Create a base URL that directs users to the directory housing your documentation. For instance:
vscode://file/${FULL_PATH_TO_CONTENT_DIRECTORY}
Note: If you're an VS Code Insiders user, kick off the URL withvscode-insiders://
. -
Configuring
edit_uri
: Modify yourmkdocs.yml
file, setting theedit_uri
option to your created URL:edit_uri: vscode-insiders://file/Users/me/Development/my-project/documentation/content/
. Note: If you aren't integrating a Git link, you can omit the optionalrepo_url
setting. -
Enabling the "Edit" Button: Activate the "Edit" button feature within MkDocs Material by updating your
mkdocs.yml
as follows:
theme:
features:
- content.action.edit
Final. Final Touch: Now, perform the documentation build process.
Results and Beyond
With these adjustments, every page of your documentation will get an "Edit" button, making the source file open in VS Code. If this solution helps you in your workflow, consider potential expansions:
- Conditional URI Setup: Leverage environment variables to configure the URI dynamically. For local use, it fires up VS Code; for hosting, it points to the Git repository.
- Beyond VS Code: If your preferred IDE differs from VS Code, explore available URI schemes that align with your choice.
- Theme Compatibility: If you're not using the Material theme, verify whether your theme supports the "Edit" button feature.
Conclusion
This approach streamlines local documentation edits while leaving room for enjoying well-organised navigation between built documentation pages. Join the discussion in the comments if you have insights to share about the potential expansions or the overall concept.
Let's document effectively with minimal effort!
Top comments (0)