Getting started
Installation
Install @nolebase/markdown-it-bi-directional-links to your project dependencies by running the following command:
ni @nolebase/markdown-it-bi-directional-links -Dpnpm add @nolebase/markdown-it-bi-directional-links -Dnpm install @nolebase/markdown-it-bi-directional-links -Dyarn add @nolebase/markdown-it-bi-directional-links -DConfiguration
Integrate with VitePress
In the VitePress configuration file (usually docs/.vitepress/config.ts, the file path and extension may be different), import @nolebase/markdown-it-bi-directional-links as a plugin, and use it as a markdown-it plugin in the markdown option:
If you've never seen a colored diff before
This is a markup rule for displaying diff in the user interface (UI).
Red parts usually represents the lines you are going to remove, commonly appeared with a Minus sign -, or you could simply understand it as: this line will be removed.
Green parts usually represents the lines you are going to add, commonly appeared with a Plus sign +, or you could simply understand it as: this line will be added.
To learn more about diff, you can check out this answer about the history of diffutils and Git's documentation
import { defineConfigWithTheme } from 'vitepress'
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'
export default defineConfigWithTheme({
lang: 'en',
title: 'Site name', // For reference only, please do not copy directly
description: 'Description', // For reference only, please do not copy directly
themeConfig: {
// Other configurations...
},
markdown: {
config: (md) => {
md.use(BiDirectionalLinks())
},
},
})Integrate on-demand
Caution
Configure on your own is for those who know and understand what they are doing. If you don't know what you are doing or encounter problems during configuration, please read and follow the Integrate with VitePress section.
Import this plugin into the file where you can access the markdown-it instance, and use it as a markdown-it plugin:
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'Then you need to use the use() member methods from the markdown-it instance to use this plugin. With a options object that contains a dir field which is the root directory of your project supplied, the value for dir field can be obtained through cwd() function call that imported from either process or node:process:
import MarkdownIt from 'markdown-it'
let markdownIt: MarkdownIt = null as unknown as MarkdownIt
// ---cut---
import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'
// Rest of the code...
// @noErrors
markdownIt.use(BiDirectionalLinks()) Configuration options
interface BiDirectionalLinksOptions {
/**
* The directory to search for bi-directional links.
*
* @default cwd() - Current working directory
*/
dir?: string
/**
* The base directory joined as href for bi-directional links.
*
* @default '/'
*/
baseDir?: string
/**
* The glob patterns to search for bi-directional linked files.
*
* @default '*.md, *.png, *.jpg, *.jpeg, *.gif, *.svg, *.webp, *.ico, *.bmp, *.tiff, *.apng, *.avif, *.jfif, *.pjpeg, *.pjp, *.png, *.svg, *.webp, *.xbm'
*/
includesPatterns?: string[]
/**
* Excludes files added from `includePatterns` from being searched if it matches at least one of these patterns.
*
* @default '_*, dist, node_modules'
*/
excludesPatterns?: string[]
/**
* Whether to include debugging logs.
*
* @default false
*/
debug?: boolean
/**
* Whether to exclude the warning when no matched file is found.
*
* @default false
*/
noNoMatchedFileWarning?: boolean
/**
* Generate an error link or a link to a specific page when no matched file is found.
*
* When you use this option, you should define a css style for
* `.nolebase-route-link-invalid` (or `a[href="#"] {}`) to
* distinguish the invalid link from the normal link. Such as:
* `a.nolebase-route-link-invalid { color: red; opacity: 0.6; }`
*
* @default false
*/
stillRenderNoMatched?: boolean
/**
* Force a relative path instead of an absolute path
*
* @default false
*/
isRelativePath?: boolean
}
Neko
Jesse Burnett
Linc