Skip to main content

Wiki template

Markdown Wiki Template

This is a template to be cloned to quickly set up a repository for keeping documentation in Markdown.

Specifically, it arranges how image files are handled.

Additionally, it provides some handy settings for VS Code users.

You may remove .markdown-wiki-template directory if you don't need this documentation.

Table of content:

Prerequisites

  • OS: GNU Linux / Mac (though it's not tested for Mac yet - it should work there)
  • git available on $PATH

Get started

Download this repository to your local machine:

git clone https://github.com/vsudakov/markdown-wiki-template.git

Images

.images directory

Keep all images in .images directory of the project root. This allows moving markdown documents across any subdirectories without the need to update links to images.

Regardless of where the markdown page is placed within the repository, all image links are related to the project root as below:

![img](/.images/sample-image.png)

img

pre-commit hook

pre-commit hook automatically detects the image files that are not referenced anywhere within the repository anymore and removes them.

To enable this pre-commit hook - run the following command within the project root directory:

chmod 755 .images/untrack-unused-images.sh; \
ln --symbolic ../../.images/untrack-unused-images.sh .git/hooks/pre-commit

markdownlint

  • usage of style checker (like this) which detects styling issues - is highly-appreciated

VS Code

For VS Code plenty of settings and extensions are available to simplify work with Markdown. The below is the list of the selected settings/extensions.

EXTENSIONS ARE NOT INSTALLED AUTOMATICALLY - each extension needs to be installed individually. But the configuration for each extension is applied automatically.

Proposed VS Code workspace settings are located in /.vscode/settings.json. These settings include both vs-code-internal and extenstion-specific settings.

You may remove /.vscode/ directory if you don't use VS Code.

VS Code internal settings

"Paste Image" extenstion

home page: https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image

installation from command palette (Ctrl + P): ext install mushan.vscode-paste-image

allows pasting images from the clipboard directly into Markdown document by pressing Ctrl + Alt + V (by default).

Every image is automatically saved in /.images/ directory using an automatically-generated name and the project-root-related-link to that is pasted in the current markdown document.

Preferences for this extension: /.vscode/settings.json#L17-L31

"Markdown All in One" extension

home page: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one

installation from command palette (Ctrl + P): ext install yzhang.markdown-all-in-one

among those numerous features what this extension provides - there is one extra useful to generate/update a table of content.

Preferences for this extension: /.vscode/settings.json#L35-L40

"markdownlint" extension

home page: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint

installation from command palette (Ctrl + P): ext install DavidAnson.vscode-markdownlint

aforementioned markdownlint style checker is available as a plugin for VS Code.

Back to top