pixelandtonic/vuepress-theme-craftdocs

VuePress theme for Craft CMS documentation

Craft Documentation Theme for VuePress

This is the VuePress theme used for Craft CMS documentation.

It makes the following changes over the default VuePress theme:

• Adds support for code language toggles and split page views.
• Disables interpolation for all inline <code> tags.
• Improves <table> styling.
• Adds themeConfig options to tweak sidebar sizing: smallerSidebarHeadings and widerSidebar. (Each false by default.)

Setup

1. Install VuePress like normal

2. Require this theme

   yarn add -D vuepress-theme-craftdocs # or npm install -D vuepress-theme-craftdocs
   

3. Set these things in .vuepress/config.js:

   module.exports = {
     // ...
     theme: "craftdocs",
     themeConfig: {
       // ...
       codeLanguages: {
         php: "PHP",
         twig: "Twig",
         // any other code language labels you want to include in code toggles...
       },
     },
     markdown: {
       anchor: { level: [2, 3] },
       extendMarkdown(md) {
         let markup = require("vuepress-theme-craftdocs/markup");
         md.use(markup);
       },
     },
   };

Code Toggles

You can create code toggles by wrapping multiple fenced code blocks with a code container:

::: code

```php
echo "Hey, $name";
```

```twig
Hey, {{ name }}
```

:::

By default, toggle labels will be pulled from the value in themeConfig.codeLanguages that matches the code block’s language. If you want to provide a custom label instead, just type it after the code block language:

::: code

```php Craft 2
$success = craft()->entries->saveEntry($entry);
```

```php Craft 3
$success = Craft::$app->elements->saveElement($entry);
```

:::

Split Views

You can create split view pages by adding split: true to your page’s frontmatter:

---
split: true
---

In split view, any content that contains a horizontal rule (---) will be divided into left and right portions, starting and ending at the closest H2/H3 headings.

## Cool Headings

Left-side content

---

Right-side content

In split view, code toggles can share a single page-wide toggle UI, floated at the top of the right-hand content pane. To do this, add a code list to your page’s frontmatter:

---
split: true
code:
  - php
  - twig
---

(Use the same language handles defined by themeConfig.codeLanguages in .vuepress/config.js.)

Upgrading from v1.3.x

1. Follow the VuePress Migration from 0.x guide.
2. Update any custom styles that relied on .content to reference .theme-default-content instead.
3. If you’re using Algolia DocSearch, make sure your index configuration’s selectors are still valid.