Configuration

This theme extends the VuePress2 Default Themeopen in new window but sets slightly different defaultsopen in new window. Theoretically all the options supported in the default theme should also be available in this one.

Before you get started its HEAVILY RECOMMENDED that you set the following parent config before proceeding. Here is what we set for the repo that generates these docs:

import {defineUserConfig} from '@vuepress/cli';
import {defaultThemePlus} from '@lando/vuepress-theme-default-plus';

export default defineUserConfig({
  ...
  theme: defaultThemePlus({
    docsDir: 'docs',
    docsBranch: 'main',
    repo: 'lando/vuepress-theme-default-plus',
  }),
  ...
});

And here is our special config:

Generic Config

alias

Type: Object
Default: {}
Details:
This allows the user to override any downstream components with their own. See thisopen in new window.

Example:

alias: {
  '@theme/Home.vue': './Home.vue'),
},

baseUrl

Type: String
Default: null
Example: baseUrl: "https://docs.lando.dev"
Details:
This allows external links to the specified baseUrl to be experentially treated like internal links. This is useful if you have multiple VuePress sites that are all tied together into a single domain experient a la Netlify's rewrite functionality.
If you don't understand what that is or you only have a single docs site then its best to just ignore this one.

contributorsExclude

Type: Array
Default: []

Example:

contributorsExclude: [
  'Mike Pirog',
  'dependabot[bot]',
]

Details:
This allows you to filter out some contributors from where contributors show up eg CustomPageMeta and GuideHeader. Note that unlike contributorsPage.exclude this is NOT NECCESARILY a GitHub username so take care to get the contributor name right.

defaults

Type: Object
Default: Hereopen in new window

Example:

defaults: {
  ga: {
    id: 'SOME ID',
  },
}

Details:
This allows you to easily extend this theme with defaults that make more sense for you. This lets you distribute common config to all the things that use it like Google Analytics IDs, shared navbar items, etc.

sharedNavbar

Type: Array
Default: []

Example:

sharedNavbar: [
  {text: 'GitHub2', link: 'https://github.com/lando/vuepress-theme-default-plus/'},
],

Details:
This prepends a bunch of entries to the usual navbar and follows the same format. It is usually used in combination with baseUrl to bring its "treat like internal link" functionality to the navbar. It also is useful if you want to extend this theme deploy a shared navbar

Alert

alert

Type: Object || Boolean
Default: false

Example:

alert: {
  content: 'Are you looking for the 3.x docs? You can go to them <a href="/3.x">here</a>.',
  scheme: 'neutral',
  closeable: true,
},

Details:
This will print an alert at the top of the page. You can pass in HTML content allow "dangerous things" will be stripped.
Setting closeable to false will persist the alert and not let the user dismiss it.
You can set a scheme for the alert which will append the alert-scheme-SCHEME class to the alert container eg alert-scheme-success. We have provided the following schemes by default: danger|warning|tip|neutral|success. If you specify a different scheme you will want to make sure to provide the alert-scheme-MYSCHEME class.
You can also configure the alert height with the --alert-height pallette variable.

Autometa

autometa

Type: Object || Boolean
Default: false

Example:

autometa: {
  twitter: '@devwithlando',
  canonicalUrl: 'https://vuepress-theme-default-plus.lando.dev/',
},

Details:
Set this if you care about the theme automatically generating common metatags.

Carbon Ads

carbonAds

Type: Object || Boolean
Default:
```
carbonAds: false
```

Example:

carbonAds: {
  placement: 'landodev',
  serve: 'CE7DCKJU',
},

Contributors Page

contributorsPage

Type: Object || Boolean
Default:
```
contributorsPage: {
  auto: true,
},
```

Full Example:

contributorsPage: {
  auto: true,
  repo: 'lando/vuepress-theme-default-plus',
  content: fs.readFileSync(path.resolve(__dirname, 'contributors.md')),
  exclude: [
    'dependabot[bot]',
  ],
  data: [{
    name: 'pirog',
    img: 'https://me.pic',
    link: 'pirog.dev',
    score: 100,
  }],
  docsBranch: 'main',
  docsDir: '',
  link: '/contributors.html',
  title: 'Contributorz',
},

Details:
This will automatically generate a page of contributors based on the data.
If you set auto to true and repo is a public GitHub repo then the theme will attempt to populate the data for you. However, if you manually set a value then the theme will prefer that. So in the above Full Example the theme will just use data instead of what is on GitHub.
If you do not set repo, docsBranch and docsDir explicitly the theme will use repo, docsBranch, docsDir instead.

Jobs

jobs

Type: Object || Boolean
Default:
```
jobs: false
```

Example:

jobs: [
  {
    title: 'Lando Developer',
    logo: 'https://docs.lando.dev/images/icon.svg',
    link: 'https://docs.google.com/forms/d/e/1FAIpQLSc2vkesq59BblKo8ZX-R1hKTrHphh1kmsg4FgWV1WH5BKEjHQ/viewform',
    company: 'Lando System Inc',
    aux: 'DC, Remote',
  },
],

Type: Object
Default:
```
columns: 3
```

Example:

navbar: [
  ...
  {
    text: 'Recipes',
    children: [
      {
        text: 'Hosting Integrations',
        columns: 2,
        children: [
          {
            text: 'Acquia',
            link: 'https://docs.lando.dev/acquia',
          },
          {
            text: 'Lagoon (beta)',
            link: 'https://docs.lando.dev/lagoon',
            alert: 'UPDATED!'
          },
          {
            text: 'Pantheon',
            link: 'https://docs.lando.dev/pantheon',
          },
          {
            text: 'Platform.sh (beta)',
            link: 'https://docs.lando.dev/platformsh',
            alert: {
              text: 'DEPRECATED!',
              type: 'danger',
              expires: 4125485593000,
            },
          },
        ],
      },
      {
        text: 'PHP Frameworks',
        children: [
          {
            text: 'Backdrop',
            link: 'https://docs.lando.dev/backdrop',
          },
        ],
      },
      ...
    },
  ]

Details:
Note that columns currently only works with "subitems" eg children that are expressed in "sections" as in the example above.
You can add the optional alert to any child item. This will add a stylized and expiring badge before the link with text of your choosing. If you make alert a string it will use that as the badge text. If you make alert an object you can also customize the style and the expiration date of the alert.
alert can be styled with setting alert.type to one of new, updated, deprecated or eol. You can automatically remove the alert at given time by setting alert.expires which must be expressed as a timestamp in milliseconds.
If a top level menu item contains any children with alerts of type new then an alert circle will appear in front of that menu item as a circle colored with the theme's primary color.

Page Types

pageTypes

Type: Array || Boolean

Default:

pageTypes: [{
  name: 'Guide',
  key: 'guide',
  path: path.resolve(__dirname, '..', 'components', 'Guide.vue'),
}, {
  name: 'Blog',
  key: 'blog',
  path: path.resolve(__dirname, '..', 'components', 'BlogPost.vue'),
}],

Details:
pageType allows you to easily add additional "custom page components". You can then use those page components by setting the key of any of the types to true in your frontmatter.
More concretely and using the example above, which is the default, you can set blog: true or guide: true in your frontmatter to use either the Guide or BlogPost components instead of the default Page component.

Reading Mode

readMode

Type: Object || Boolean
Default: true

Example:

readMode: {
  focusName: 'MAKE READING EASIER',
  distractName: 'MAKE READING HARDER',
},

Details:
Configure the way "Reading Mode" is set up or disable it completely with false.

Robots.txt

Type: Object
Default:
```
robots: {
  allowAll: true,
},
```

Example:

robots: {
  host: 'https://vuepress-theme-default-plus.lando.dev/',
  sitemap: 'https://vuepress-theme-default-plus.lando.dev/sitemap.xml,
  disallowAll: false,
  allowAll: false,
  policies: [
    {
      userAgent: '*',
      disallow: [
        '/user/',
        '/login'
      ],
      allow: [
        '*.js',
        '*.png'
      ]
    }
  ]
},

Details:

If disallowAll is set to true, it will ignore all other options and exclude everything on the site from indexing. allowAll is set to true by default and this ignores the policies option.

To use the policies option, make sure both disallowAll and allowAll are set to false.

You can specify host and sitemap directly. If you omit them the theme will attempt to set them if it can and it makes sense.

Search

search

Type: Object || Boolean
Default:
```
search: false
```

Example:

Docsearch

search: {
  appId: 'BH4D9OD16A',
  apiKey: '15e332feefe9ec96929f44c62f6c88',
  indexName: 'lando',
  searchBase: 'https://docs.lando.dev',
},

default search

search: true

Details:

Set to true to turn on the default search functionality. If you wish to leverage Docsearchopen in new window then you also need to pass in an appId, apiKeyandindexName`.

Note that if you want to search across many sites that operate under a single domain then you will also need to set the searchBase. If you have not set searchBase it will use baseUrl instead.

sidebarHeader

Type: Object || Boolean
Default: false

Full Example:

sidebarHeader: {
  auto: true,
  repo: 'lando/vuepress-theme-default-plus',
  icon: './icon.png',
  title: 'Current Version',
  version: null,
  link: null,
  satisifies: undefined,
  type: 'tip',
}

Details:
sidebarHeader allows you to give greater context and organization around the secondary sidebar menu. This is particularly useful if you have a single site that combines the docs of many projects together.
If you set auto to true and repo is a public GitHub repo then the theme will attempt to populate the other values for you. However, if you manually set a value then the theme will prefer that. So in the above Full Example the theme will set version and link automatically but will use Current Version for the title.
If you are using auto you can also specify satisfies which is a semveropen in new window comparision string. This will use the first entry from the resulting subset of releases. Note that this also assumes the name of your GitHub release is a semver compatible string.
You can specify type and it will wrap the version badge in badge TYPE. By default it is badge tip. If you modify this you will need to define the badge TYPE style eg if you set type: hot then you will need to define badge hot in CSS.
If you do not set repo explicitly the theme will try to use repo instead.
icon is optional and puts the specificed icon to the left of the title.

Sitemap.xml

Type: Object
Default:
```
sitemap: true
```

Example:

sitemap: {
  baseUrl: 'https://stuffandthings.com',
  changefreq: 'daily',
  priority: 0.5,
  urls: [
    'stuff.html',
    'things.html,
  ],
  exclude: [
    'badstuff.html'
  ],
},

Details:

If the baseUrl above is not specified then the theme will try to use autometa.canonicalurl and then the generic.baseUrl. You can also globally set the changefreq and priority for all pages that do not have them defined in their frontmatter.

You can also add additional urls that may not get picked up in the pages object via urls. You can also choose to exclude certain urls via the exclude option array as well.

Frontmatter

You can override the global config for the following options via the frontmatter of any page:

---
sitemap:
  exclude: false
  changefreq: hourly
  priority: 1.0
---

Type: Object || Boolean
Default:
```
social: false
```

Example:

social: {
  enabled: true,
  owner: '@devwithlando',
  icons: [{
    title: 'Twitter',
    svg: {
      attributes: {
        'viewBox': '0 0 24 24',
        'fill': 'none',
        'stroke-width': 2,
        'stroke-linecap': 'round',
        'stroke-linejoin': 'round',
      },
      path: {
        d: 'M23 3a10.9 10.9 0 0 1-3.14 1.53 4.48 4.48 0 0 0-7.86 3v1A10.66 10.66 0 0 1 3 4s-4 9 5 13a11.64 11.64 0 0 1-7 2c9 5 20 0 20-11.5a4.5 4.5 0 0 0-.08-.83A7.72 7.72 0 0 0 23 3z',
      },
    },
    link: 'https://twitter.com/devwithlando',
  },
},

hubspot

Type: Object || Boolean
Default: false
Example:
```
hubspot: {
  id: null,
}
```
Details:
Set if you want to hookup Hubspot tracking codes. id needs to be the id in //js.hs-scripts.com/${ID}.js.

Versions Page

versionsPage

Type: Object || Boolean

Default:

versionsPage: {
  auto: true,
  trimLatest: true,
  satisfies: null,
  showEdge: true,
},

Full Example:

versionsPage: {
  auto: true,
  repo: 'lando/vuepress-theme-default-plus',
  content: fs.readFileSync(path.resolve(__dirname, 'versions.md')),
  data: [{
    name: '3.1.4',
    href: `https://github.com/pi/pi/tree/3.1.4`,
    target: '_blank',
    rel: 'noopener noreferrer',
  }],
  docsBranch: 'main',
  docsDir: '',
  link: '/versions.html',
  satisfies: '>0.9',
  showEdge: false,
  title: 'Previous Versions',
  trimLatest: true,
},

Details:
This will automatically generate a page of previous versions based on the data.
If you set auto to true and repo is a public GitHub repo then the theme will attempt to populate the data for you. However, if you manually set a value then the theme will prefer that. So in the above Full Example the theme will just use data instead of what is on GitHub.
If you do not set repo, docsBranch and docsDir explicitly the theme will use repo, docsBranch, docsDir instead.
trimLatest will pop off the most recent version. showEdge can be either a URL or true.
You can also specify satisfies which is a semveropen in new window comparision string. This will only show the satisfied subset of data.name versions.

Configuration

Generic Config

alias

baseUrl

contributorsExclude

defaults

sharedNavbar

Alert

alert

Autometa

autometa

Carbon Ads

carbonAds

Contributors Page

contributorsPage

Jobs

jobs

Navbar

navbar

Page Types

pageTypes

Reading Mode

readMode

Robots.txt

Robots.txt

Search

search

Sidebar Header

sidebarHeader

Sitemap.xml

Sitemap.xml

Sponsors

sponsors

Tagging

tags

Tracking

ga

hubspot

Versions Page

versionsPage

# Configuration

# Generic Config

# alias

# baseUrl

# contributorsExclude

# defaults

# sharedNavbar

# Alert

# alert

# Autometa

# autometa

# Carbon Ads

# carbonAds

# Contributors Page

# contributorsPage

# Jobs

# jobs

# Navbar

# navbar

# Page Types

# pageTypes

# Reading Mode

# readMode

# Robots.txt

# Robots.txt

# Search

# search

# Sidebar Header

# sidebarHeader

# Sitemap.xml

# Sitemap.xml

# Social

# social

# Sponsors

# sponsors

# Tagging

# tags

# Tracking

# ga

# hubspot

# Versions Page

# versionsPage

Configuration

Generic Config

alias

baseUrl

contributorsExclude

defaults

sharedNavbar

Alert

alert

Autometa

autometa

Carbon Ads

carbonAds

Contributors Page

contributorsPage

Jobs

jobs

Navbar

navbar

Page Types

pageTypes

Reading Mode

readMode

Robots.txt

Robots.txt

Search

search

Sidebar Header

sidebarHeader

Sitemap.xml

Sitemap.xml

Social

social

Sponsors

sponsors

Tagging

tags

Tracking

ga

hubspot

Versions Page

versionsPage