Publishing

Global

siteUrl

  • type: string
  • default: N/A
  • required: false

Description

Set the URL the site will be published under. All links will be prefixed with this URL.

siteUrl will always be the base URL, while assetsPrefix may need to be used when using publishing services like GitHub Pages, GitLab Pages, and others when you aren't using a custom domain name.

Example

If you are publishing with a custom domain, such as https://example.com, siteUrl will be that URL.

  publishing:
    siteUrl: https://example.com

siteRootDir

  • type: string
  • default: docs
  • required: true

Description

Set the directory where your website will be built. This path is relative to your workspace root.

Example

  publishing:
    siteRootDir: docs # will build site under {workspace root}/docs/

siteIndex

Description

Set the note that will be the home of your published site.

Example

  publishing:
    siteIndex: foo
    siteHierarchies:
      - dendron
      - foo
      - bar

siteHierarchies

  • type: string[]
  • default: [root]
  • required: true

Description

Set the list of hierarchies to publish

NOTE: root is a special value. When this is set, all hierarchies are published. If you want to publish specific hierarchies, remove root and list out hierarchies that you want to publish

Example

  • publishing all notes
  publishing:
    siteHierarchies:
      - root
  • publishing specific colors
  publishing:
    siteHierarchies:
      - dendron
      - community
      - topic

hierarchy

  • type: object
  • default: N/A
  • required: false

Description

Set per-hierarchy publishing configurations.

For each hierarchy you wish to configure, you can set the hierarchy name as the key and use the following properties:

Example

publishing:
  hierarchy:
    fooHiearchy:
      publishByDefault: ...
      customFrontmatter: ...

enableFMTitle

  • type: boolean
  • default: true
  • required: false

Description

Enable rendering frontmatter property title as title of the note.

Example

  publishing:
    enableFMTitle: false

enablePrettyRefs

  • type: boolean
  • default: true
  • required: false

Description

Enable rendering note references as pretty refs in published notes.

See Pretty Ref for more information.

Example

  publishing:
    enablePrettyRefs: true

enableSiteLastModified

  • type: boolean
  • default: true
  • required: true

Description

Enable displaying the last modified date at the bottom of your published notes.

Example

  publishing:
    enableSiteLastModified: false

  • type: boolean
  • default: true
  • required: false

Description

Enable using note titles when displaying naked links in a published note.

This also applies to note references.

If set to false, the entire hierarchy string will be used for rendering the links.

Example

  publishing:
    enableNoteTitleForLink: true

enableHierarchyDisplay

  • type: boolean
  • default: true
  • required: false

Description

Enable rendering hierarchies (Children) list at the end of the note.

The text used for the title of the block can be set by hierarchyDisplayTitle

Example

  publishing:
    enableHierarchyDisplay: true
    hierarchyDisplayTitle: Children

enableKatex

  • type: boolean
  • default: true
  • required: false

Description

Enable rendering Katex typesetting in published notes.

See Math for more information.

Example

  publishing:
    enableKatex: true

enableFrontmatterTags

❗ Note that currently this will also affect how frontmatter tags will be rendered in Preview. This will later be fixed.

  • type: boolean
  • default: true
  • required: true

Description

Enable rendering frontmatter tags in published notes.

See Frontmatter tags for more information.

Example

  publishing:
    enableFrontmatterTags: false

enableHashesForFMTags

❗ Note that currently this will also affect how frontmatter tags will be rendered in Preview. This will later be fixed.

  • type: boolean
  • default: false
  • required: true

Description

Enable rendering frontmatter tags with the # symbol prefix in published notes.

See Frontmatter tags for more information.

Example

  publishing:
    enableFrontmatterTags: true
    enableHashesForFMTags: true

enableRandomlyColoredTags

❗ Note that currently this will also affect how tags will be rendered in Preview. This will later be fixed.

  • type: boolean
  • default: true
  • required: false

Description

Enable automatically generated colors for tags when the tag color isn't specified.

If disabled, only the tags that have colors explicitly set will have the color rendered, and the rest will be rendered identical to regular links.

Example

  publishing:
    enableRandomlyColoredTags: false

enableTaskNotes

❗ Note that currently this will also affect how tags will be rendered in Preview. This will later be fixed.

  • type: boolean
  • default: true
  • required: false

Description

When enabled, links to task notes will have a checkmark, and will display task owner and due date. You can disable this view by setting this configuration to false.

Example

publishing:
  enableTaskNotes: false

copyAssets

  • type: boolean
  • default: true
  • required: false

Description

Copy assets from vault to published website.

Example

  publishing:
    copyAssets: true

assetsPrefix

  • type: string
  • default: N/A
  • required: false

Description

Prefix all urls with the given prefix

By default, assets are served from the root (/). Adding an assetsPrefix will change the url that pages are served from.

Example

# in this case, it will serve requests from /foo
publishing:
  assetsPrefix: foo

logoPath

  • type: string
  • default: N/A
  • required: false

Description

Set the path to a logo image.

The logo will appear in the site header, and will be used as a default image if no image frontmatter property is set for a published note.

The value can be either:

  • a path, which will be relative to the workspace root.
  • a web URL starting with http or https, in which case Dendron will use the provided URL as-is.

Example

  publishing:
    logoPath: https://example.com/logo

siteFaviconPath

  • type: string
  • default: N/A
  • required: false

Description

Set the path to favicon.

The value is relative to the workspace root.

Example

  publishing:
    siteFaviconPath: public

writeStubs

  • type: boolean
  • default: false
  • required: true

Description

Set how stub notes are handled when publishing.

If set to true, all stub notes that are getting published will be written to the file system as an empty note in your vault. Writing stubs will guarantee a permanent URL for the published stub notes.

If set to false, stub notes will not be written to the file system. Note that any link to the stub notes will not be permanent, and will be randomized every time it is published. This is because a stub note that isn't written to the filesystem will always have a randomly generated temporary note id.

See Stubs for more information.

Example

  publishing:
    writeStubs: true

customHeaderPath

  • type: string
  • default: N/A
  • required: false

Description

Set the path to a custom header file which will be included in all published pages.

This path is relative to the workspace root.

Example

  publishing:
    customHeaderPath: header.html

duplicateNoteBehavior

  • type: object
  • default: N/A
  • required: false

Description

Set the strategy to handle duplicate notes in a multi-vault workspace.

Currently, only the useVault action is allowed.

It takes a list of vault names as payload. When a duplicate is found, Dendron will go through the provided list sequentially and resolve to the first vault that matches.

Note that this is done automatically when you run the Vault Add command.

Example

If a duplicate note is found, try resolving them in vault1 first, then followed by vault2 and then finally vault3.

publishing: 
  duplicateNoteBehavior: # if a duplcate note is found,
    action: useVault
    payload: # try resolving them in this order of vault match
      - vault1
      - vault2
      - vault3

hierarchyDisplayTitle

  • type: string
  • default: Children
  • required: false

Description

Set the text to be used as the heirarchy display block's title.

enableHierarchyDisplay needs to be enabled for this to be in effect.

Example

  publishing:
    enableHierarchyDisplay: true
    hierarchyDisplayTitle: Children

ga

❗ Please note that, we (Dendron as an organization) do not track analytics on user's personal published sites. This configuration option is for providing your own tracking number if you wish to do so for your own purposes.

Description

Configuration namespace that holds all Google Analytics related publishing settings.

Below is an overview of what the ga namespace looks like:

  publishing:
    ga:
      tracking:

tracking

  • type: string
  • default: N/A
  • required: false

Description

Set the optional Google Analytics Tracking ID to embed in your published website.

Google Analytics tracking will not be enabled when previewing your site with Dendron: Publish Dev

Example

  publishing:
    ga:
      tracking: UA-000000-2

seo

Summary

Configuration namespace that holds all SEO related publishing settings.

Below is an overview of what the seo namespace looks like:

  publishing:
    seo:
      title:
      description:
      author:
      twitter:
      image:
        url:
        alt:

title

  • type: string
  • default: Dendron
  • required: false

Description

Set the title of the page.

Example

  publishing:
    seo:
      title: My Awesome Knowledge Base


description

  • type: string
  • default: Personal Knowledge Space
  • required: false

Description

Default description for the site.

If the note has a desc property, it will be overwritten by the content from desc

Example

publishing:
  seo:
    description: Everything I know


author

  • type: string
  • default: N/A
  • required: false

Description

Set the author.

Example

  publishing:
    seo:
      author: John Doe


twitter

  • type: string
  • default: N/A
  • required: false

Description

Set the Twitter handle.

Example

  publishing:
    seo:
      twitter: https://twitter.com/dendronhq


image

  • type: object
  • default: N/A
  • required: false

Description

Set the default image for the published site.

The image will show up in preview on social media websites. If this isn't configured, no image will be used when sharing links to pages on the published site.

Images can also be set at the note level with, and are configured with the same settings (url, alt). Images at the note level will override the default image set in dendron.yml.

Syntax

image:
  url: string, uri to the image
  alt: string, alt text of the image

Examples

Setting site wide image

publishing:
  seo:
    image:
      url: https://org-dendron-public-assets.s3.amazonaws.com/images/blog-mobile-editor-header.png
      alt: A tree with many branches in full bloom

Setting a note specific image

---
...
image:
  url: https://org-dendron-public-assets.s3.amazonaws.com/images/blog-mobile-editor-header.png
  alt: A tree with many branches in full bloom
---

Blog header

github

Summary

Configuration namespace that holds all GitHub related publishing settings.

Below is an overview of what the github namespace looks like:

publishing:
  github:
    cname:
    enableEditLink:
    editLinkText:
    editViewMode:
    editBranch:
    editRepository:

cname

  • type: string
  • default: N/A
  • required: false

Description

Set the CNAME used for GitHub Pages publishing.

Example

  publishing:
    github:
      cname: wiki.dendron.so


  • type: boolean
  • default: true
  • required: true

Description

Enable adding a link at the bottom of a published page that lets users edit the page.

Example

  publishing:
    github:
      enableEditLink: true


editLinkText

  • type: string
  • default: Edit this page on GitHub
  • required: false

Description

Set the text to be used with the edit link when enabled by enableEditLink.

enableEditLink needs to be set to true for this to take effect.

Example

  publishing:
    github:
      enableEditLink: true
      editLinkText: Click here to edit this note


editViewMode

  • type: tree | edit
  • default: tree
  • required: false

Description

Set how the users should be redirected when clicking on the edit link.

  • tree mode will open the note's location in the repository.
  • edit mode will open an editor that could be used to commit / create pull request with changes.

Example

  publishing:
    github:
      editViewMode: `edit`


editBranch

  • type: string
  • default: main
  • required: false

Description

Set the branch that the edit link should redirect to.

Example

  publishing:
    github:
      editBranch: staging


editRepository

  • type: string
  • default: N/A
  • required: false

Description

Set the URL of the project's GitHub repository.

This will be used to redirect users to the correct repository when the edit link is clicked.

Example

  publishing:
    github:
      editRepository: https://github.com/dendronhq/dendron-site

giscus

All required fields in this configuration namespace can be generated through the configuration tool

To learn more about Giscus, please refer to Giscus

Summary

Configuration namepsace that holds all Giscus related publishing settings.

Below is an overview of what the giscus namespace looks like:

publishing:
  giscus:
    id:
    host:
    repo:
    repoId:
    category:
    categoryId:
    mapping:
    term:
    theme:
    strict:
    reactionsEnabled:
    emitMetadata:
    inputPosition:
    lang:
    loading:

id

  • type: string
  • default: N/A
  • required: false

Description

Set the id of the Giscus component.

Example

  publishing:
    giscus:
      id: comments


host

This is only required if you wish to self-host Giscus.
Remove this configuration from dendron.yml if you are not self hosting.

  • type: string
  • default: N/A
  • required: false

Description

Host of the Giscus server.

Example

  publishing:
    giscus:
      host: my-custom-host.com


repo

The string should be formatted in the following form:
{user name}/{repo name} for personal repositories {organization name}/{repo name} for organization repositories

  • type: ${string}/${string}
  • default: N/A
  • required: true

Descroption

Repository where the discussion is stored..

Example

  publishing:
    giscus:
      repo: "dendronhq/dendron-site"


repoId

Please use the configuration tool to figure out your repository ID.
When you select your public repository from the tool, the ID will be automatically generated.

  • type: string
  • default: N/A
  • required: true

Description

ID of the repository where the discussion is stored

Example

  publishing:
    giscus:
      repoId: "1234567890"


category

  • type: string
  • default: N/A
  • required: false

Description

Category where the discussion will be searched

Example

  publishing:
    giscus:
      category: "Announcements"


categoryId

Please use the configuration tool to figure out your category ID.
When you select your public repository from the tool, you will be given a dropdown of available Github Discussions categories in your repository.
When you select the category from the dropdown, the category ID will be automatically be generated.

  • type: string
  • default: N/A
  • required: false

Description

ID of the category where the discussion will be searched.

Example

  publishing:
    giscus:
      categoryId: "1234567890"


mapping

  • type: url | title | og:title | specific | number | pathname
  • default: N/A
  • required: true

Description

Set the mapping between the parent page and the discussion.

Example

  publishing:
    giscus:
      mapping: "pathname"


term

⚠️ Due to limitations, this configuration currently has no effect when publishing your notes with Dendron.

  • type: string
  • default: N/A
  • required: false

Description

Search term to use when searching for the discussion

Example

  publishing:
    giscus:
      term: "term"


theme

⚠️ Due to limitations, experimental custom theme support is limited when publishing your notes with Dendron.
Only the provided themes are supported.

  • type: | light | light_high_contrast | light_protanopia | light_tritanopia | dark | dark_high_contrast | dark_protanopia | dark_tritanopia | dark_dimmed | transparent_dark | preferred_color_scheme
  • default: N/A
  • required: false

Description

Theme that Giscus will be displayed in.

Example

  publishing:
    giscus:
      theme: preferred_color_scheme


strict

  • type: 0 | 1
  • default: N/A
  • required: false

Description

Use strict title matching.

Example

  publishing:
    giscus:
      strict: "0"


reactionsEnabled

  • type: 0 | 1
  • default: N/A
  • required: false

Description

Enable reactions to the main post of the discussion.

Example

  publishing:
    giscus:
      reactionsEnabled: "1"


emitMetadata

  • type: 0 | 1
  • default: N/A
  • required: false

Description

Emit the discussion metadata periodically to the parent page.

Example

  publishing:
    giscus:
      emitMetadata: "0"


inputPosition

  • type: top | bottom
  • default: N/A
  • required: true

Description

Placement of the comment box.

Example

  publishing:
    giscus:
      inputPosition: "top"


lang

  • type: | de | gsw | en | es | fr | id | it | ja | ko | nl | pl | pt | ro | ru | tr | vi | zh-CN | zh-TW
  • default: N/A
  • required: false

Description

Language that Giscus will be displayed in.

Example

  publishing:
    giscus:
      lang: "en"


loading

  • type: lazy | eager
  • default: N/A
  • required: false

Description

Whether the iframe should be loaded lazily or eagerly.

Example

  publishing:
    giscus:
      loading: "lazy"

Note

  • type: boolean
  • default: false
  • frontmatter: only

Description

Should exclude children from the published tree view

Example

Without nav_exclude_children

With nav_exclude_children


Backlinks