Markdown::Publish

Appearance

Extend generated configuration ​

Most projects want to retain generated paths and navigation while adding a theme choice, search, social links, or validation policy. Use config_extend for that case. Use config when you intend to own the native engine configuration instead. Supplying both is an error.

MkDocs supplemental YAML ​

MkDocs inherits the named YAML before the publisher supplies its assembly paths and navigation.

perl
publish => {
    module        => 'mkdocs',
    config_extend => 'doc/mkdocs/site.yml',
},
yaml
theme:
  name: material
  features:
    - navigation.sections
markdown_extensions:
  - admonition

VitePress extension function ​

VitePress loads an ECMAScript module. Its default export receives the generated VitePress configuration and a context object.

javascript
export default (config, context) => ({
  ...config,
  description: `${context.name} reference`,
  themeConfig: {
    ...config.themeConfig,
    search: {provider: 'local'},
  },
});

Docusaurus extension function ​

Docusaurus loads a CommonJS module. It returns the complete configuration to use.

javascript
module.exports = (config, context) => ({
  ...config,
  tagline: `${context.name} reference`,
  onBrokenLinks: 'throw',
});

Starlight extension function ​

Starlight separates Astro configuration from the options passed to the Starlight integration. Return both objects. Extra Astro integrations are retained after the generated Starlight integration.

javascript
export default ({astro, starlight}, context) => ({
  astro,
  starlight: {
    ...starlight,
    description: `${context.name} reference`,
    social: [{
      icon: 'github',
      label: 'GitHub',
      href: 'https://github.com/example/example-client',
    }],
  },
});