diff --git a/docs/configuration.md b/docs/configuration.md index d9cdfd05b1..7b61752984 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -275,6 +275,24 @@ window.$docsify = { }; ``` +## pageTitleFormatter + +- Type: `Function` +- Default: `null` + +Optional function to customize how the site `name` is used when composing the document title. If provided, Docsify will call this function with the configured `name` (which may contain HTML) and use the returned string as the title portion for the site name — Docsify will not automatically strip HTML or otherwise modify the value. If not provided, Docsify falls back to the default behavior of stripping HTML tags from `name`. + +Basic example — strip HTML and trim (equivalent to Docsify's default behavior): + +```js +window.$docsify = { + name: 'My Site', + pageTitleFormatter(name) { + return name ? name.replace(/<[^>]+>/g, '').trim() : ''; + }, +}; +``` + ## hideSidebar - Type : `Boolean` @@ -456,7 +474,7 @@ window.$docsify = { ## name -- Type: `Boolean | String` +- Type: `Boolean|String` Website name as it appears in the sidebar. diff --git a/src/core/config.js b/src/core/config.js index f433b33d06..b2e2fdb9e2 100644 --- a/src/core/config.js +++ b/src/core/config.js @@ -27,6 +27,7 @@ const defaultDocsifyConfig = () => ({ fallbackLanguages: /** @type {null | string[]} */ (null), fallbackDefaultLanguage: '', formatUpdated: /** @type {string | ((updatedAt: string) => string)} */ (''), + pageTitleFormatter: /** @type {null | ((name: string) => string)} */ (null), /** For the frontmatter plugin. */ frontMatter: /** @type {Record | null} */ (null), hideSidebar: false, diff --git a/src/core/event/index.js b/src/core/event/index.js index 1fd7abce9b..e9c446cee0 100644 --- a/src/core/event/index.js +++ b/src/core/event/index.js @@ -323,13 +323,21 @@ export function Events(Base) { * @void */ onRender() { - const { name } = this.config; + const { name, pageTitleFormatter } = this.config; const currentPath = this.router.toURL(this.router.getCurrentPath()); const currentSection = dom .find(`.sidebar a[href='${currentPath}']`) ?.getAttribute('title'); - const plainName = name ? name.replace(/<[^>]+>/g, '').trim() : name; + // If a pageTitleFormatter is provided, let the user format the name + // (no automatic HTML stripping). Otherwise, default to stripping + // HTML tags from the configured name. + const plainName = + typeof pageTitleFormatter === 'function' && typeof name === 'string' + ? pageTitleFormatter(name) + : name + ? name.replace(/<[^>]+>/g, '').trim() + : name; const currentTitle = plainName ? currentSection ? `${currentSection} - ${plainName}`