Split site up similarly to 0.26 site

Author: Gerrit0

.config/typedoc.json

@@ -36,6 +36,11 @@
     "categorizeByGroup": false,
     "categoryOrder": ["Reflections", "Types", "Comments", "*"],
     "groupOrder": ["Common", "*"],
+    "navigationLinks": {
+        "Docs": "https://typedoc.org",
+        "Example": "https://typedoc.org/example/index.html",
+        "GitHub": "https://github.com/TypeStrong/typedoc"
+    },
     "validation": {
         "notExported": true,
         "invalidLink": true,

.vscode/settings.json

@@ -42,7 +42,7 @@
     "eslint.workingDirectories": [".", "./example"],
     "mochaExplorer.configFile": ".config/mocha.test-explorer.json",
     // Ignore usernames in the Thanks sections of the changelog
-    "cSpell.ignoreRegExpList": ["/^- +@[A-Z0-9_]+/igm"],
+    "cSpell.ignoreRegExpList": ["/^- +@[A-Z0-9_-]+/igm"],
     "cSpell.words": [
         "callouts",
         "cname",
@@ -60,6 +60,7 @@
         "shiki",
         "tsbuildinfo",
         "tsdoc",
+        "typedoc",
         "typeof",
         "typestrong",
         "uncategorized",

example/src/documents/markdown.md

@@ -29,7 +29,7 @@ A TypeScript code block:
 const x: number | string = 12
 ```
 
-See {@link syntaxHighlightingShowcase | `syntaxHighlightingShowcase`} for more code blocks.
+See [the syntax highlighting showcase](./syntax-highlighting.md) for more code blocks.
 
 ## A List
 

example/typedoc.json

@@ -12,12 +12,10 @@
         "Classes": 1.5
     },
     "navigationLinks": {
-        "Docs": "https://typedoc.org/guides/overview",
+        "Docs": "https://typedoc.org",
+        "API": "https://typedoc.org/api/index.html",
         "GitHub": "https://github.com/TypeStrong/typedoc"
     },
-    "sidebarLinks": {
-        "API": "https://typedoc.org/api"
-    },
     "highlightLanguages": [
         "typescript",
         "tsx",

scripts/build_site.sh

@@ -5,13 +5,26 @@ set -e
 node bin/typedoc --help --logLevel Error > site/generated/help.txt
 node scripts/generate_site_plugins.js
 
-# Build the API docs, only build JSON output here to remove ~2s from
-# the time it takes to run this script.
-# node bin/typedoc --json docs/docs.json --readme none
+# Build the API docs
+if [[ -n "$CI" || ! -d docs ]]; then
+    node bin/typedoc --html docs --json docs/docs.json --readme none
+fi
+
+# Build the example
+if [[ -n "$CI" || ! -d example/docs ]]; then
+    cd example
+    npm i
+    npm run typedoc -- --logLevel Error
+    cd ..
+fi
 
 # Build the actual site, references the API docs
 node bin/typedoc --options site/typedoc.config.jsonc
 
 # Create/copy static files
 node scripts/generate_options_schema.js docs-site/schema.json
+# cspell: words googlede
 cp site/googlede482cdb17c37ad4.html docs-site/googlede482cdb17c37ad4.html
+
+cp -r example/docs docs-site/example
+cp -r docs docs-site/api

site/development/index.md

@@ -34,7 +34,7 @@ Output is split into two folders, for JSON output see the `src/lib/serialization
 
 Plugins may effect any part of the process after step 2 by listening to events
 fired by each component or adding / replacing handlers for a given task. As an
-example, the {@link Converter | Converter} fires events before
+example, the [Converter](https://typedoc.org/api/classes/Converter.html) fires events before
 starting conversion, when declarations are converted and when the project should
 be resolved.
 
@@ -62,7 +62,7 @@ run it with `--help` to see a summary of the available options.
 
 For more detailed information about the implementation and API surface of each
 component, consult its API documentation. All components are available on the
-{@link Application} class, which is passed to plugins.
+[Application](https://typedoc.org/api/classes/Application.html) class, which is passed to plugins.
 
 ### Options
 
@@ -84,9 +84,9 @@ There are 11 builtin option types as specified by the [ParameterType](https://ty
 -   `GlobArray` - An array of globs. Globs will be resolved if they do not start with `**`, after skipping leading `!` and `#` characters.
 
 Options are discovered and set by option readers, which are documented in the
-{@link Configuration.OptionsReader} interface.
+[Configuration.OptionsReader](https://typedoc.org/api/interfaces/Configuration.OptionsReader.html) interface.
 
-Plugins can declare their own options by calling {@link Options.addDeclaration}
+Plugins can declare their own options by calling [Options.addDeclaration](https://typedoc.org/api/classes/Configuration.Options.html#adddeclaration)
 
 ### Plugins
 
@@ -114,7 +114,10 @@ export function load(app: Application) {
 
 ### Converters
 
-TypeDoc converts the syntax tree created by TypeScript into its own structure of {@link Models.Reflection | Reflections} to allow themes and serialization to work with a standard object format. Conversion is done primarily in three files.
+TypeDoc converts the syntax tree created by TypeScript into its own structure of
+[Reflections](https://typedoc.org/api/classes/Models.Reflection.html) to allow
+themes and serialization to work with a standard object format. Conversion is
+done primarily in three files.
 
 -   [symbols.ts](https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/symbols.ts) - contains converters for each `ts.Symbol` that is exported from entry points.
 -   [types.ts](https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/types.ts) - contains converters for `ts.Type`s and `ts.TypeNode`s.
@@ -123,11 +126,14 @@ TypeDoc converts the syntax tree created by TypeScript into its own structure of
 ### JSON Output
 
 TypeDoc can produce JSON output which can be consumed by other tools. The format
-of this JSON is defined by the {@link JSONOutput.ProjectReflection} interface.
-If plugins want to cause custom properties to be included in the output JSON,
-they can achieve this by adding a serializer to {@link Serializer }. If custom
-properties are added, they should generally also be revived with a {@link
-Deserializer} so that they can be used with TypeDoc's packages mode.
+of this JSON is defined by the
+[JSONOutput.ProjectReflection](https://typedoc.org/api/interfaces/JSONOutput.ProjectReflection.html)
+interface. If plugins want to cause custom properties to be included in the
+output JSON, they can achieve this by adding a serializer to
+[Serializer](https://typedoc.org/api/classes/Serializer.html). If custom
+properties are added, they should generally also be revived with a
+[Deserializer](https://typedoc.org/api/classes/Deserializer.html) so that they
+can be used with TypeDoc's packages mode.
 
 ### HTML Output
 

site/development/internationalization.md

@@ -39,6 +39,7 @@ translation keys include numbers to indicate placeholders in the English string,
 the translated strings should include `{n}` where the placeholder will be filled in at
 runtime.
 
+> [!IMPORTANT]
 > Please do not submit machine generated translations for languages you are unfamiliar with.
 > TypeDoc relies on contributors to ensure the accuracy of included translations.
 
@@ -58,8 +59,7 @@ to them as suggested in the example above.
 
 Plugins may use TypeDoc's internationalization module to provide multiple
 translations for strings declared within them. To do this, they should call
-{@link Internationalization.Internationalization.addTranslations |
-Application.internationalization.addTranslations} with their expected values.
+[Application.internationalization.addTranslations] with their expected values.
 
 The `addTranslations` method expects that all translatable strings have been
 declared in the `TranslatableStrings` interface. To do this, use declaration
@@ -88,3 +88,5 @@ export function load(app: td.Application) {
     app.logger.info(app.i18n.plugin_example_hello_0("TypeDoc")); // Logs "Hello TypeDoc!"
 }
 ```
+
+[Application.internationalization.addTranslations]: https://typedoc.org/api/classes/Internationalization.Internationalization.html#addtranslations

site/development/plugins.md

@@ -5,12 +5,13 @@ summary: Overview of how to write a TypeDoc plugin
 
 # Writing a TypeDoc Plugin
 
-TypeDoc supports plugins which can modify how projects are converted, how converted symbols
-are organized, and how they are displayed, among other things. Plugins are Node modules which
-export a single `load` function that will be called by TypeDoc with the {@link Application} instance
-which they are to be attached to. Plugins should assume that they may be loaded multiple times
-for different applications, and that a single load of an application class may be used to convert
-multiple projects.
+TypeDoc supports plugins which can modify how projects are converted, how
+converted symbols are organized, and how they are displayed, among other things.
+Plugins are Node modules which export a single `load` function that will be
+called by TypeDoc with the [Application] instance which they are to be attached
+to. Plugins should assume that they may be loaded multiple times for different
+applications, and that a single load of an application class may be used to
+convert multiple projects.
 
 Plugins may be either ESM or CommonJS.
 
@@ -24,22 +25,31 @@ export function load(app) {
 }
 ```
 
-Plugins affect TypeDoc's execution by attaching event listeners to one or many events that will be
-fired during conversion and rendering. Events are available on the {@link Application}, {@link Converter},
-{@link Renderer}, and {@link Serializer}/{@link Deserializer} classes. There are static `EVENT_*` properties on those
-classes which describe the available events.
+Plugins affect TypeDoc's execution by attaching event listeners to one or many
+events that will be fired during conversion and rendering. Events are available
+on the [Application], [Converter], [Renderer], and [Serializer]/[Deserializer]
+classes. There are static `EVENT_*` properties on those classes which describe
+the available events.
 
-The best way to learn what's available to plugins is to browse the docs, or look at the source code
-for existing plugins. There is a list of currently supported plugins at https://typedoc.org/guides/plugins/
+The best way to learn what's available to plugins is to browse the docs, or look
+at the source code for existing plugins. There is a list of currently supported
+plugins at https://typedoc.org/guides/plugins/
 
-TypeDoc also provides several control hooks for plugins to change it's behavior, they are described
-by the [third party symbols](./third-party-symbols.md) and [custom themes](./themes.md) documents.
+TypeDoc also provides several control hooks for plugins to change it's behavior,
+they are described by the [third party symbols](./third-party-symbols.md) and
+[custom themes](./themes.md) documents.
 
-Plugins which are configurable can add custom options with `app.options.addDeclaration`. [typedoc-plugin-mdn-links]
-has an example of the recommended way of doing this.
+Plugins which are configurable can add custom options with
+`app.options.addDeclaration`. [typedoc-plugin-mdn-links] has an example of the
+recommended way of doing this.
 
-If you have specific questions regarding plugin development, please open an issue or ask in the
-[TypeScript Discord] #typedoc channel.
+If you have specific questions regarding plugin development, please open an
+issue or ask in the [TypeScript Discord] #typedoc channel.
 
 [typedoc-plugin-mdn-links]: https://github.com/Gerrit0/typedoc-plugin-mdn-links/blob/main/src/index.ts
 [TypeScript Discord]: https://discord.gg/typescript
+[Application]: file:///home/gerrit/Desktop/typedoc/docs-site/api/classes/Application.html
+[Converter]: file:///home/gerrit/Desktop/typedoc/docs-site/api/classes/Converter.html
+[Renderer]: file:///home/gerrit/Desktop/typedoc/docs-site/api/classes/Renderer.html
+[Serializer]: file:///home/gerrit/Desktop/typedoc/docs-site/api/classes/Serializer.html
+[Deserializer]: file:///home/gerrit/Desktop/typedoc/docs-site/api/classes/Deserializer.html

site/development/themes.md

@@ -16,11 +16,11 @@ export function load(app: Application) {
 }
 ```
 
-This isn't very interesting since it exactly duplicates the default theme.
-Most themes need to adjust the templates in some way. This can be done by
-providing them class which returns a different context class. Say we wanted
-to replace TypeDoc's default footer with one that mentioned your copyright.
-This could be done with the following theme.
+This isn't very interesting since it exactly duplicates the default theme. Most
+themes need to adjust the templates in some way. This can be done by providing
+them class which returns a different context class. Say we wanted to replace
+TypeDoc's default footer with one that mentioned your copyright. This could be
+done with the following theme.
 
 In this case, it would probably be better to add this content using a render
 hook for `footer.begin` or `footer.end`, but it can be done in this way as well.
@@ -55,10 +55,11 @@ export function load(app: Application) {
 
 ## Hooks
 
-When rendering themes, TypeDoc's default theme will call several functions to allow plugins to inject HTML
-into a page without completely overwriting a theme. Hooks live on the parent `Renderer` and may be called
-by child themes which overwrite a helper with a custom implementation. As an example, the following plugin
-will cause a popup on every page when loaded.
+When rendering themes, TypeDoc's default theme will call several functions to
+allow plugins to inject HTML into a page without completely overwriting a theme.
+Hooks live on the parent `Renderer` and may be called by child themes which
+overwrite a helper with a custom implementation. As an example, the following
+plugin will cause a popup on every page when loaded.
 
 ```tsx
 import { Application, JSX } from "typedoc";
@@ -71,15 +72,16 @@ export function load(app: Application) {
 }
 ```
 
-For documentation on the available hooks, see the {@link RendererHooks |
-RendererHooks} documentation on the website.
+For documentation on the available hooks, see the [RendererHooks] documentation
+on the website.
 
 ## Async Jobs
 
-Themes which completely override TypeDoc's builtin renderer may need to perform some async initialization
-or teardown after rendering. To support this, there are two arrays of functions available on `Renderer`
-which plugins may add a callback to. The renderer will call each function within these arrays when rendering
-and await the results.
+Themes which completely override TypeDoc's builtin renderer may need to perform
+some async initialization or teardown after rendering. To support this, there
+are two arrays of functions available on `Renderer` which plugins may add a
+callback to. The renderer will call each function within these arrays when
+rendering and await the results.
 
 ```ts
 import { Application, RendererEvent } from "typedoc";
@@ -99,3 +101,5 @@ export function load(app: Application) {
     });
 }
 ```
+
+[RendererHooks]: https://typedoc.org/api/interfaces/RendererHooks.html

site/development/third-party-symbols.md

@@ -4,21 +4,28 @@ title: Third Party Symbols
 
 # Third Party Symbols
 
-TypeDoc 0.22 added support for linking to third party sites by associating a symbol name with npm packages.
-
-Since TypeDoc 0.23.13, some mappings can be defined without a plugin by setting [`externalSymbolLinkMappings`][externalSymbolLinkMappings].
-This should be set to an object whose keys are package names, and values are the `.` joined qualified name
-of the third party symbol. If the link was defined with a user created declaration reference, it may also
-have a `:meaning` at the end. TypeDoc will _not_ attempt to perform fuzzy matching to remove the meaning from
-keys if not specified, so if meanings may be used, a url must be listed multiple times.
-
-Global external symbols are supported, but may have surprising behavior. TypeDoc assumes that if a symbol was
-referenced from a package, it was exported from that package. This will be true for most native TypeScript packages,
-but packages which rely on `@types` will be linked according to that `@types` package for that package name.
-
-Furthermore, types which are defined in the TypeScript lib files (including `Array`, `Promise`, ...) will be
-detected as belonging to the `typescript` package rather than the `global` package. In order to support both
-`{@link !Promise}` and references to the type within source code, both `global` and `typescript` need to be set.
+TypeDoc 0.22 added support for linking to third party sites by associating a
+symbol name with npm packages.
+
+Since TypeDoc 0.23.13, some mappings can be defined without a plugin by setting
+[`externalSymbolLinkMappings`][externalSymbolLinkMappings]. This should be set
+to an object whose keys are package names, and values are the `.` joined
+qualified name of the third party symbol. If the link was defined with a user
+created declaration reference, it may also have a `:meaning` at the end. TypeDoc
+will _not_ attempt to perform fuzzy matching to remove the meaning from keys if
+not specified, so if meanings may be used, a url must be listed multiple times.
+
+Global external symbols are supported, but may have surprising behavior. TypeDoc
+assumes that if a symbol was referenced from a package, it was exported from
+that package. This will be true for most native TypeScript packages, but
+packages which rely on `@types` will be linked according to that `@types`
+package for that package name.
+
+Furthermore, types which are defined in the TypeScript lib files (including
+`Array`, `Promise`, ...) will be detected as belonging to the `typescript`
+package rather than the `global` package. In order to support both `{@link
+!Promise}` and references to the type within source code, both `global` and
+`typescript` need to be set.
 
 ```jsonc
 // typedoc.json
@@ -54,12 +61,14 @@ A wildcard can be used to provide a fallback link to any unmapped type.
 ## Plugins
 
 Plugins can add support for linking to third party sites by calling
-{@link Converter.addUnknownSymbolResolver | `app.converter.addUnknownSymbolResolver`}
+[Converter.addUnknownSymbolResolver]
 
-If the given symbol is unknown, or does not appear in the documentation site, the resolver may return `undefined`
-and no link will be rendered unless provided by another resolver.
+If the given symbol is unknown, or does not appear in the documentation site,
+the resolver may return `undefined` and no link will be rendered unless provided
+by another resolver.
 
-The following plugin will resolve a few types from React to links on the official React documentation site.
+The following plugin will resolve a few types from React to links on the
+official React documentation site.
 
 ```ts
 import { Application, type DeclarationReference } from "typedoc";
@@ -106,8 +115,8 @@ export function load(app: Application) {
 ```
 
 Since TypeDoc 0.23.26, plugins may also return return an object for more control
-over the displayed link. The returned `caption` will be used if the user does not
-specify the link text.
+over the displayed link. The returned `caption` will be used if the user does
+not specify the link text.
 
 ```ts
 import { Application, type DeclarationReference } from "typedoc";
@@ -156,11 +165,16 @@ export function load(app: Application) {
 }
 ```
 
-The unknown symbol resolver will also be passed the reflection containing the link
-and, if the link was defined by the user, the {@link Models.CommentDisplayPart} which was parsed into the
-{@link DeclarationReference} provided as the first argument.
+The unknown symbol resolver will also be passed the reflection containing the
+link and, if the link was defined by the user, the [Models.CommentDisplayPart]
+which was parsed into the [DeclarationReference] provided as the first argument.
 
-If `--useTsLinkResolution` is on (the default), it may also be passed a {@link Models.ReflectionSymbolId}
-referencing the symbol that TypeScript resolves the link to.
+If `--useTsLinkResolution` is on (the default), it may also be passed a
+[Models.ReflectionSymbolId] referencing the symbol that TypeScript resolves the
+link to.
 
 [externalSymbolLinkMappings]: https://typedoc.org/options/comments/#externalsymbollinkmappings
+[Converter.addUnknownSymbolResolver]: https://typedoc.org/api/classes/Converter.html#addUnknownSymbolResolver
+[Models.CommentDisplayPart]: https://typedoc.org/api/types/Models.CommentDisplayPart.html
+[DeclarationReference]: https://typedoc.org/api/interfaces/DeclarationReference.html
+[Models.ReflectionSymbolId]: https://typedoc.org/api/classes/Models.ReflectionSymbolId.html