Creating Symlinks for Multiple Project Readmes in a Material MkDocs Site

If you're building an internal documentation site using Material MkDocs and would like to provide symlinks to multiple project readmes in a git repository's docs/ folder, you're in the right place! This article will cover the key concepts and provide a detailed guide on how to achieve this.

Symlinks, or symbolic links, are special files that serve as shortcuts to other files or directories in a file system. By creating symlinks to multiple project readmes, you can easily access and navigate to different project documentation without having to manually switch between repositories.

Key Concepts

• Symlinks: Special files that serve as shortcuts to other files or directories.
• Material MkDocs: A static site generator that simplifies the creation of beautiful, customizable documentation sites.

Creating Symlinks

To create symlinks for multiple project readmes in a Material MkDocs site, follow these steps:

1. Navigate to the docs/ folder: This is where you'll create the symlinks for your project readmes.

cd path/to/your/docs/folder

2. Create the symlinks: Use the ln -s command to create the symlinks. Replace project1, project2, and project3 with the actual names of your projects, and replace path/to/project1/readme.md, path/to/project2/readme.md, and path/to/project3/readme.md with the actual paths to your project readmes.

ln -s path/to/project1/readme.md project1.md
ln -s path/to/project2/readme.md project2.md
ln -s path/to/project3/readme.md project3.md

3. Verify the symlinks: Use the ls -l command to verify that the symlinks have been created correctly.

ls -l

You should see the symlinks listed as shortcuts to the original files.

Including Symlinks in Material MkDocs

To include the symlinks in your Material MkDocs site, you'll need to add them to your mkdocs.yml configuration file.

1. Open the mkdocs.yml file: This file is located in the root directory of your documentation site.

nano mkdocs.yml

2. Add the symlinks to the nav section: The nav section is where you define the navigation for your site. Add the symlinks as new entries in this section.

nav:
  - Project 1: project1.md
  - Project 2: project2.md
  - Project 3: project3.md

3. Save and close the mkdocs.yml file: Use the Ctrl+X keyboard shortcut to save and close the file.

4. Rebuild the site: Use the mkdocs build command to rebuild your site and include the new symlinks.

mkdocs build

Summary

In this article, we've covered the key concepts of symlinks and Material MkDocs, and provided a detailed guide on how to create symlinks for multiple project readmes in a Material MkDocs site. By following these steps, you can easily access and navigate to different project documentation without having to manually switch between repositories.

References

• Symlinks - Arch Linux Wiki
• Material MkDocs - Getting Started

HTML Unordered List

• Types of References:
  • Books
    • Articles
    • Online Resources