Enabling Local Editing for MkDocs Documentation with IDE

Introduction

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

1. Understanding the Configuration: Familiarise yourself with the edit_uri configuration option in the MkDocs documentation.

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

3. 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 with vscode-insiders://.

4. Configuring edit_uri: Modify your mkdocs.yml file, setting the edit_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 optional repo_url setting.

5. Enabling the "Edit" Button: Activate the "Edit" button feature within MkDocs Material by updating your mkdocs.yml as follows:

    theme:
    	features:
    		- content.action.edit

6. 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!