SpellBook

Appearance

VitePress ​

As a developer, I've often found myself wondering how major companies manage to keep their documentation so well-organized, sleek, and consistent in terms of user interface. It's quite an intriguing puzzle! That's when I stumbled upon the VitePress Static Site Generator(SSG) framework. I'm excited to dive into it and see how it can level up our documentation game, especially when paired with Obsidian. 😎🚀

🛠 Setup ​

shell
# Install Vitepress
yarn add vitepress

# Initialize Vitepress
yarn vitepress init

When promoted, Make sure to initialise the config under ./docs or you can choose your own. I would also recommend to use Default Theme (Out of the box, good-looking docs) (Saves lots of time juggling around😛).

🎨Theme config ​

The theme config's location is at your/project/path/.vitepress/config.mts. cache directory will store all the static pages generated by VitePress while runnning on dev or project build

⚙ Site config ​

VitePress will not build if it detects dead links by default. To avoid this behaviour, there is a quick hack

typescript
export default { 
	ignoreDeadLinks: true, 
}

➕ Plugins ​

Wikilink is common way of linking documents using markdown files in Obsidian.

md
// use of wikilink
Hello, I am [[wikilink]]
// use of external link
Hello, I am [wikilink](URL)

Bad news is wikilinks are not supported in VitePress natively. Good news is we have plugin for it called markdown-it-wikilinks

Installation & Usage ​

shell
yarn add markdown-it-wikilinks

Add to config with:

typescript
import wikilinks from 'markdown-it-wikilinks';

export default defineConfig({
	...,
	markdown: {
		config: (md) => {
			md.use(wikilinks({
				/* Your wikilinks options. */
			}))
		}
	}
});

Default sidebar config which displays files look something like below

typescript
export default {
	themeConfig: {
	    sidebar: [{
	        text: 'Guide',
	        items: [{
	            text: 'Introduction',
	            link: '/introduction',
	          },
	          {
	            text: 'Getting Started',
	            link: '/getting-started',
	          }],
	      }],
	},
};

This approach is not practical when we are dealing with lots of files. For automatic sidebar configuration, use [vitepress-sidebar](https://github.com/jooy2/vitepress-sidebar/tree/0cf2f1f11d8024ced72f3a659e937f9f6de75053)

Installation & Usage ​

shell
yarn add -D vitepress-sidebar
typescript
import { defineConfig } from 'vitepress';
import { generateSidebar } from 'vitepress-sidebar';

export default defineConfig({
	themeConfig: {
		sidebar: generateSidebar({
			documentRootPath: "docs/"
		}),
	},
});