Skip to content

VuePress theme for Craft CMS documentation

License

Notifications You must be signed in to change notification settings

pixelandtonic/vuepress-theme-craftdocs

Repository files navigation

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.