Using "vuepress" theme independently

[arantes555]

trafficstars

It appears currently impossible to use the "vuepress" theme (which is the "markdown" theme with the vuepress-specific slugification : https://github.com/tgreyuk/typedoc-plugin-markdown/commit/78cd78fa5d0ddf0f328459e715099085c45b3b23 ), without using the vuepress-plugin-typedoc plugin for VuePress. What I want to do is just use typedoc to generate markdown files which can then later be used in VuePress.

The problem is that vuepress-plugin-typedoc is the package which contains this code, and it is a VuePress plugin, not a typedoc plugin.

The possible solutions are, in my opinion :

• move this "vuepress" typedoc theme code to a new package (typedoc-theme-vuepress or typedoc-plugin-vuepress?)
• move this "vuepress" typedoc theme code to the typedoc-plugin-markdown package (so that it defines 2 separate themes)
• export a valid typedoc plugin from the vuepress-plugin-typedoc package (not necessarily from the default file, it could be under a subpath, as long as it is in the package.json exports)

Currently, I have to use a workaround : I created a custom file with the following code:

/* eslint-disable no-useless-escape, no-control-regex, @typescript-eslint/no-var-requires */
const typedocPluginMarkdown = require('typedoc-plugin-markdown')

const rControl = /[\u0000-\u001f]/g
const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’–—<>,.?/]+/g
const rCombining = /[\u0300-\u036F]/g

function slugify (str) {
  // Split accented characters into components
  return (
    str
      .normalize('NFKD')
      // Remove accents
      .replace(rCombining, '')
      // Remove control characters
      .replace(rControl, '')
      // Replace special characters
      .replace(rSpecial, '-')
      // Remove continuous separators
      .replace(/\-{2,}/g, '-')
      // Remove prefixing and trailing separators
      .replace(/^\-+|\-+$/g, '')
      // ensure it doesn't start with a number (#121)
      .replace(/^(\d)/, '_$1')
      // lowercase
      .toLowerCase()
  )
}

class VuepressTheme extends typedocPluginMarkdown.MarkdownTheme {
  toAnchorRef (reflectionId) {
    return slugify(reflectionId)
  }
}

function load (app) {
  typedocPluginMarkdown.load(app)
  app.renderer.defineTheme('vuepress', VuepressTheme)
}

exports.load = load

And use this in typedoc.json:

{
// ...
  "plugin": ["../../typedoc-theme-vuepress.js"],
  "theme": "vuepress",
// ...
}

Obviously, avoinding this custom workaround would be preferable.

Thank you !

[tgreyuk]

The only thing that the the Vuepress theme is currently doing is slugifying the anchors, so it might be better just to expose an additional option to the main plugin --anchors slugify (or something like that). It would mean that the Vuepress-plugin only responsibiity would be to bootstrap typedoc through the vuepress config and generate the sidebar (which is probably a nicer separation of concern anyway).

[arantes555]

@tgreyuk You are right, that would be a nice way of going about it.

[tgreyuk]

Have created a package for Vitepress theme that works outside of the plugin eco system. Will also work with VuePress. https://github.com/tgreyuk/typedoc-plugin-markdown/tree/next/packages/typedoc-vitepress-theme#readme . I think this will supersede the VuePress plugins. Currently requires pre-release versions to be installed.

[tgreyuk]

https://typedoc-plugin-markdown.org/plugins/vitepress