A custom vuepress theme with mermaid and plantuml, katex and vue components.

Overview

Build Status npm version downloads

Personal Documentation Theme for VuePress

Currently, completely refactoring code for vuepress v1, all components should be compatible.

This is the VuePress theme used for personal documentation. It has libaries for markdown-based diagramming tools, sortable/filterable table components and chartjs.

An example repo is available at Vuepress Theme Cool Starter

Demo

Setup For Vuepress V1

  1. The theme was refactored completely to inherit from the base vuepress theme. Make sure to install the V1 for vuepress yarn install --global [email protected]

  2. Get the latest version of the theme

    yarn install -D vuepress-theme-cool
  3. Set up .vuepress/config.js. A minimual setup is below, note that mermaid does not need to be included as a plugin.

```js
// .vuepress/config.js
// this represents the minimal configuration
module.exports = {
  theme: 'cool',
  markdown: {
    extendMarkdown: md => {
      md.set({ html: true })
      md.use(require('markdown-it-katex'))
      md.use(require('markdown-it-plantuml'))
      md.use(require('markdown-it-admonition'))
    }
  }
}
```
  1. If you are adding vuepress to your local project, set up package.json and your file directory looks something like this
├ package.json
├ docs
├── .vuepress
├──── components
├──── public
├──── config.js
├──── index.styl
├──── palette.styl
├── Readme.md 
├──Readme.md
├── foo
├──── README.md
├──── doc1.md
└── cool
├──── doc2.md

If any issues arise, please review the documentation at https://v1.vuepress.vuejs.org/miscellaneous/migration-guide.html. The sample diagrams are components should work as it.

Setup For Vuepress V0

See VuepressV0

Creating Diagrams

Plantuml

Plantuml can be used like

@startuml
strict digraph meme {
  exists [color=blue]
  authenticate [color=blue]
  require
  create
  UserCreated
  destroy
  UserDestroyed
  get [color=blue]
  authenticate -> require
  create -> UserCreated
  destroy -> require
  destroy -> UserDestroyed
  get -> require
}
@enduml

Mermaid

In addition to use mermaid diagrams add an components, taken from Vuepress Issue 111, obviously I expect vuepress to natively support mermaid, or have tighter integration in the future.

">
// .vuepress/components/mermaid.vue

<template>
  <div class="mermaid">
    <slot></slot>
  </div>
</template>

<script>
export default {
  mounted() {
    import("mermaid/dist/mermaid").then(m => {
      m.initialize({
        startOnLoad: true
      });
      m.init();
    });
  }
};
</script>

Mermaid components can be used like

<mermaid>
graph TD
  A[Cool] -->|Get money| B(Go shopping)
  B --> C{Let me}
  C -->|Two| D[Laptop]
  C -->|Two| E[iPhone]
  C -->|Three| F[Car]
  C -->|Four| F[Mac]
</mermaid>

Timeline

Road to Graduation First Year 1A First Year 1B Accepted Computer Engineering ENGR 1C (extra courses) Second Year 2A ENGR 2.5 Second Year 2B ENGR 001 ENGR 002 Third Year (3 classes) Third Year 3B Third Year 3A ENGR 003 ENGR 004 Fourth Year 4B Fourth Year 4A ">
// .vuepress/components/sample-timeline.vue
<template>
  <timeline timeline-theme="lightblue">
    <timeline-title bg-color="#09FFAA">Road to Graduation</timeline-title>
    <timeline-item bg-color="#9dd8e0">First Year 1A</timeline-item>
    <timeline-item bg-color="#9dFFe0">First Year 1B</timeline-item>
    <timeline-item bg-color="#FFF000">Accepted Computer Engineering</timeline-item>
    <timeline-item bg-color="#cFe8eF">ENGR 1C (extra courses)</timeline-item>
    <timeline-item bg-color="#97Aec8">Second Year 2A</timeline-item>
    <timeline-item bg-color="#5744D4">ENGR 2.5</timeline-item>
    <timeline-item bg-color="#0F4859">Second Year 2B</timeline-item>
    <timeline-item bg-color="#094341">ENGR 001</timeline-item>
    <timeline-item bg-color="#825F03">ENGR 002</timeline-item>
    <timeline-item bg-color="#954F08">Third Year (3 classes)</timeline-item>
    <timeline-item bg-color="#A71490">Third Year 3B</timeline-item>
    <timeline-item bg-color="#C084A9">Third Year 3A</timeline-item>
    <timeline-item bg-color="#7B71C2">ENGR 003</timeline-item>
    <timeline-item bg-color="#2348B1">ENGR 004</timeline-item>
    <timeline-item bg-color="#915F15">Fourth Year 4B</timeline-item>
    <timeline-item bg-color="#0909FA">Fourth Year 4A</timeline-item>
  </timeline>
</template>
 
<script>
import { Timeline, TimelineItem, TimelineTitle } from 'vue-cute-timeline'
 
export default {
  components: {
    Timeline,
    TimelineItem,
    TimelineTitle
  }
}
</script>

and render it in the markdown file using .

Using math

Katex can be created within a markdown file by, note that the necessary style sheet for markdown-it-katex is included in Layout.vue .

$x^2=4$

Rendering Charts

Using chartjs and vue-chartkick, allows for easy chart rendering from inside markdown files. What is good about vue-chartkick is highlightjs and google charts can be used instead.

For example the snippet below generates a pie chart, see chartjs for more details.

">
<pie-chart :data="[['Blueberry', 44], ['Strawberry', 23]]" :download="true" download="test"></pie-chart>

Sortable and Filterable tables

For sortable and filterable tables, I am using the vue-good-table which has documentation in vuepress. In order to generate tables, use an vue component under .vuepress/components

">
//.vuepress/components/my-component.vue
<template>
  <div>
    <vue-good-table
      :columns="columns"
      :rows="rows"
     />
  </div>
</template>

<script>
import { VueGoodTable } from 'vue-good-table';

export default {
  name: 'my-component',
  // add to component
  components: { VueGoodTable},
  data(){
    return {
      columns: [
        {
          label: 'Name',
          field: 'name',
        },
        {
          label: 'Age',
          field: 'age',
          type: 'number',
        },
        {
          label: 'Created On',
          field: 'createdAt',
          type: 'date',
          dateInputFormat: 'YYYY-MM-DD',
          dateOutputFormat: 'MMM Do YY',
        },
        {
          label: 'Percent',
          field: 'score',
          type: 'percentage',
        },
      ],
      rows: [
        { id:1, name:"John", age: 20, createdAt: '201-10-31:9: 35 am',score: 0.03343 },
        { id:2, name:"Jane", age: 24, createdAt: '2011-10-31', score: 0.03343 },
        { id:3, name:"Susan", age: 16, createdAt: '2011-10-30', score: 0.03343 },
        { id:4, name:"Chris", age: 55, createdAt: '2011-10-11', score: 0.03343 },
        { id:5, name:"Dan", age: 40, createdAt: '2011-10-21', score: 0.03343 },
        { id:6, name:"John", age: 20, createdAt: '2011-10-31', score: 0.03343 },
      ],
    };
  },
};
</script>

In addition, use an custom style component to get the css classes for the production build.

">
//.vuepress/components/Styles.vue
<script>
import "vue-good-table/dist/vue-good-table.css";

export default {
  name: "Styles",
};
script>

<style>
style>

Render the table by placing in a markdown file.

Disclaimer

If you see any bugs feel free to make a pull request at Github or email me. Not a expert in vuepress at all or vue so there are ways to improve my implementations. In addition, some of the components do not work, do not hesitate to message me.

Donate

If you would like to motivate me to spend more time improving open source projects please consider donating.

Donate with Ethereum

Donate with Bitcoin

paypal

Comments
  • fail to install after adding this package with version

    fail to install after adding this package with version "^1.3.0"

    "yarn dev" is successful, but webpage doesn't show anything. I opened console and saw the following error info:

    index.js?5156:3 Uncaught ReferenceError: global is not defined at eval (index.js?5156:3) at Object../node_modules/has-symbols/index.js (app.js:3156) at webpack_require (app.js:769) at fn (app.js:130) at eval (GetIntrinsic.js?e9ac:39) at Object../node_modules/es-abstract/GetIntrinsic.js (app.js:3108) at webpack_require (app.js:769) at fn (app.js:130) at eval (callBind.js?44b7:5) at Object../node_modules/es-abstract/helpers/callBind.js (app.js:3120)

    opened by franklinqin0 5
  • dev doesn't work

    dev doesn't work

    Describe the bug Build working fine but when i run npm run docs:dev then it throws console errors and blank page

    To Reproduce Steps to reproduce the behavior: run npm run docs:dev

    Expected behavior it should run dev server without any errors.

    opened by lorvent 4
  • Allow for default plantuml notation

    Allow for default plantuml notation

    Hi,

    could we allow a default plantuml notation like it is recognized by Gitlab, for example?

    Then it would look like this:

    ` ` `plantuml
    @startuml
    
    @enduml
    ` ` `
    

    If I understand it correctly, for now a PLantuml diagram is not recognized if there are three backticks before and after the start/close tags

    enhancement 
    opened by chbndrhnns 4
  • 'vuepress build' cannot find vue-good-table styles

    'vuepress build' cannot find vue-good-table styles

    I can use the vuepress dev . command and see my docs in the browser. However, when I run vuepress build ., I receive the following error:

      WAIT  Rendering static HTML...
    Rendering page: /how-to/ FAIL  Error rendering /how-to/:
    Error: Cannot find module 'vue-good-table/dist/vue-good-table.css?vue&type=style&index=0&lang=css&'
        at Function.Module._resolveFilename (module.js:547:15)
        at Function.Module._load (module.js:474:25)
        at Module.require (module.js:596:17)
        at require (internal/module.js:11:18)
        at r (/Users/jo/.config/yarn/global/node_modules/vue-server-renderer/build.js:8346:16)
        at Object.<anonymous> (webpack:/external "vue-good-table/dist/vue-good-table.css:1:0)
        at __webpack_require__ (webpack/bootstrap:25:0)
        at VueComponent.injectStyles (.vuepress/components/demo-table.vue:6:0)
        at VueComponent.hook (Users/jo/.config/yarn/global/node_modules/vuepress/node_modules/vue-loader/lib/runtime/componentNormalizer.js:53:0)
        at callHook (/Users/jo/.config/yarn/global/node_modules/vue/dist/vue.runtime.common.js:2919:21)
        at VueComponent.Vue._init (/Users/jo/.config/yarn/global/node_modules/vue/dist/vue.runtime.common.js:4624:5)
        at new VueComponent (/Users/jo/.config/yarn/global/node_modules/vue/dist/vue.runtime.common.js:4796:12)
        at createComponentInstanceForVnode (/Users/jo/.config/yarn/global/node_modules/vue-server-renderer/build.js:7353:10)
        at renderComponentInner (/Users/jo/.config/yarn/global/node_modules/vue-server-renderer/build.js:7527:40)
        at renderComponent (/Users/jo/.config/yarn/global/node_modules/vue-server-renderer/build.js:7502:5)
        at resolve (/Users/jo/.config/yarn/global/node_modules/vue-server-renderer/build.js:7563:9)
     ⚙
    

    I need to comment the