Getting started

Word count

395 words

Reading time

3 minutes

Installation

Install @nolebase/markdown-it-bi-directional-links to your project dependencies by running the following command:

@antfu/ni

ni @nolebase/markdown-it-bi-directional-links -D

pnpm

pnpm add @nolebase/markdown-it-bi-directional-links -D

npm

npm install @nolebase/markdown-it-bi-directional-links -D

yarn

yarn add @nolebase/markdown-it-bi-directional-links -D

Configuration

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 {  } from 'vitepress'
import {  } from '@nolebase/markdown-it-bi-directional-links'

export default ({
  : 'en',
  : 'Site name', // For reference only, please do not copy directly
  : 'Description', // For reference only, please do not copy directly
  : {
    // Other configurations...
  },
  : {
    : () => {
      .(()) 
    },
  },
})

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 {  } 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 {  } from '@nolebase/markdown-it-bi-directional-links'

// Rest of the code...
.(()) 

Configuration options

interface BiDirectionalLinksOptions {
  /**
   * The directory to search for bi-directional links.
   *
   * @default cwd() - Current working directory
   */
  ?: string
  /**
   * The base directory joined as href for bi-directional links.
   *
   * @default '/'
   */
  ?: 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'
   */
  ?: string[]
  /**
   * Whether to include debugging logs.
   *
   * @default false
   */
  ?: boolean
  /**
   * Whether to exclude the warning when no matched file is found.
   *
   * @default false
   */
  ?: boolean
}

Contributors

Neko

Changelog

Last edited about 14 hours agoView full history

9e6d7-refactor(bi-directional-links): better logging (#215)

e690e-docs: refactored docs to better guide users