doc: organize navigation

docs/architecture.md

@@ -1,3 +1,7 @@
+---
+category: Development
+---
+
 # markdown-it design principles
 
 ## Data flow

docs/development.md

@@ -1,3 +1,7 @@
+---
+category: Development
+---
+
 # Development recommendations
 
 Before continuing, make sure you've read:
@@ -10,17 +14,17 @@ Before continuing, make sure you've read:
 ## General considerations for plugins.
 
 1. Try to find the right place for your plugin rule:
-  - Will it conflict with existing markup (by priority)?
-    - If yes - you need to write an inline or block rule.
-    - If no - you can morph tokens within core chains.
-  - Remember that token morphing in core chains is always more simple than writing
-    block or inline rules, if you don't copy existing ones. However,
-    block and inline rules are usually faster.
-  - Sometimes, it's enough to only modify the renderer, for example, to add
-    header IDs or `target="_blank"` for the links.
-  - Plugins should not require the `markdown-it` package as dependency in `package.json`.
-    If you need access to internals, those are available via a parser instance,
-    passed on plugin load. See properties of main class and nested objects.
+   - Will it conflict with existing markup (by priority)?
+     - If yes - you need to write an inline or block rule.
+     - If no - you can morph tokens within core chains.
+   - Remember that token morphing in core chains is always more simple than writing
+     block or inline rules, if you don't copy existing ones. However,
+     block and inline rules are usually faster.
+   - Sometimes, it's enough to only modify the renderer, for example, to add
+     header IDs or `target="_blank"` for the links.
+   - Plugins should not require the `markdown-it` package as dependency in `package.json`.
+     If you need access to internals, those are available via a parser instance,
+     passed on plugin load. See properties of main class and nested objects.
 2. Search existing
    [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
    or [rules](https://github.com/markdown-it/markdown-it/tree/master/src),

src/common/utils.ts

@@ -5,12 +5,14 @@ import * as mdurl from 'mdurl'
 import * as ucmicro from 'uc.micro'
 import { decodeHTMLStrict } from 'entities'
 
-type Constructor = new (...args: any[]) => object
+/** @hidden */
+type ClassToWrap = new (...args: any[]) => object
 
-function callable<T extends Constructor> (
+/** Wraps a class so it can be called with or without `new`. */
+function callable<T extends ClassToWrap> (
   cls: T
 ): T & ((...args: ConstructorParameters<T>) => InstanceType<T>)
-function callable<T extends Constructor> (cls: T) {
+function callable<T extends ClassToWrap> (cls: T) {
   const wrapper = function (...args: ConstructorParameters<T>) {
     const newTarget =
       new.target && new.target !== wrapper

src/helpers/parse_link_title.ts

@@ -3,6 +3,7 @@
 
 import { unescapeAll } from '../common/utils.ts'
 
+/** @inline */
 interface ParseLinkTitleResult {
   ok: boolean
   can_continue: boolean

src/index.ts

@@ -1,6 +1,7 @@
 import { callable } from './common/utils.ts'
 import MarkdownItClass from './markdownit.ts'
 
+/** @category Main */
 const MarkdownIt = callable(MarkdownItClass)
 
 export default MarkdownIt

src/markdownit.ts

@@ -224,6 +224,8 @@ function normalizeLinkText (url: string): string {
  *   }
  * });
  * ```
+ *
+ * @category Main
  */
 class MarkdownIt {
   /**

src/ruler.ts

@@ -1,3 +1,4 @@
+/** @inline */
 type RuleOptions = { alt?: string[] }
 
 /**

src/rules_inline/state_inline.ts

@@ -5,12 +5,14 @@ import { isWhiteSpace, isPunctCharCode, isMdAsciiPunct } from '../common/utils.t
 import type MarkdownIt from '../markdownit.ts'
 import type { Delimiter, Env } from '../types.ts'
 
+/** @inline */
 interface ScannedDelimiters {
   can_open: boolean
   can_close: boolean
   length: number
 }
 
+/** @inline */
 type StateTokenMeta = Record<string, unknown> & {
   delimiters?: Delimiter[]
 }

src/token.ts

@@ -1,6 +1,9 @@
 // Token class
 
+/** @inline */
 type TokenNesting = -1 | 0 | 1
+
+/** @inline */
 type TokenAttribute = [name: string, value: string | number]
 
 /** Create new token and fill passed properties. */

src/types.ts

@@ -34,6 +34,7 @@ export interface Delimiter {
   jump?: number
 }
 
+/** @category Main */
 export interface MarkdownItOptions {
   /** Enable HTML tags in source. */
   html: boolean

typedoc.config.mjs

@@ -0,0 +1,28 @@
+export default {
+  entryPoints: ['src/index.ts'],
+
+  projectDocuments: [
+    'docs/architecture.md',
+    'docs/development.md'
+  ],
+  alwaysCreateEntryPointModule: false,
+
+  plugin: ['typedoc-plugin-missing-exports'],
+  excludeExternals: true,
+  placeInternalsInOwningModule: true,
+
+  out: 'apidoc',
+  includeVersion: true,
+  markdownLinkExternal: true,
+  sourceLinkExternal: true,
+  sourceLinkTemplate: 'https://github.com/markdown-it/markdown-it/blob/{gitRevision:short}/{path}#L{line}',
+  navigationLinks: {
+    GitHub: 'https://github.com/markdown-it/markdown-it'
+  },
+  defaultCategory: 'Plugin API',
+  categoryOrder: ['Main', 'Plugin API', 'Development', '*'],
+  sort: ['source-order'],
+  navigation: {
+    includeCategories: true
+  }
+}

typedoc.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["src/index.ts"],
-  "plugin": ["typedoc-plugin-missing-exports"],
-  "out": "apidoc",
-  "includeVersion": true,
-  "markdownLinkExternal": true,
-  "sourceLinkExternal": true,
-  "sourceLinkTemplate": "https://github.com/markdown-it/markdown-it/blob/{gitRevision:short}/{path}#L{line}",
-  "navigationLinks": {
-    "GitHub": "https://github.com/markdown-it/markdown-it"
-  },
-  "defaultCategory": "markdown-it",
-  "categoryOrder": ["markdown-it", "*"],
-  "sort": ["source-order"],
-  "navigation": {
-    "includeCategories": true
-  }
-}