About

Information tends to be shared across projects and coworkers causing it to get extremely fragmented and feeding one of the biggest frustration of developers even more. Kits and boilerplates in repositories are already a great step in the right direction. But that is just part of the solution around centralising all the team's knowledge

Guidelines

Some guidelines are necessary to keep everything organised and maintainable.

• Always review new content with the rest of the team. Information needs to be clear and understandable. Call up a few other developers to see if everything seems ok to be pushed to the repository.
• Make sure the repository's version and the web version are in sync. The moment a version is accepted on GIT, it should be built to the host.
• Keep folder structure and navigation structure synced.

VuePress 2

The tool we're using to gather everything in one place is VuePress 2. The bundler reads out MarkDown with extra functionalities files and turns them into static html pages with extra features like automatic content table generation, clean front-end ui, code examples, ...

Why VuePress 2?

The web contains many tools to bundle up information for development teams. Great examples are docsify and Docusaurus. We chose VuePress 2 because it is written in Vue.js. Since we decided to use Vue as a framework to work with when it comes to developing apps for websites and Showpad, it seemed to be a great match. Our experience with Vue can come in handy to add extra functionalities to this tool as we deemed necessary.

Markdown Enhance

Our Vuepress build comes with the plugin-md-enhance plugin to add even more functionalities to the markdown files. Currently activated plugins are:

• Card
• Code-Tabs
• Custom Container
• Footnote
• Include files
• Mermaid
• Playground
• Vue Playground
• Tabs
• Task list

Other plugins may be activated in the future, we just have to make sure we keep everything organized.

Guide

Some quick information about the structure of this wiki project.

Add Page

As mentioned above, make sure the directory tree mirrors the main navigation! Every MD file is a page inside VuePress. Just add a new MD file to the /docs and start writing.

Main Navigation

The navigation can be found in the header at the top of every page. It can be configured in vuepress.config.mjs that can be found in the root of the project.

Edit the navbar array of theme.navbar to manage the links of this menu.

Markdown Enhance plugin activation

All plugins are deactivated by default. Add a boolean of the same name as the plugin that needs to be activated in vuepress.config.mjs under plugins in the mdEnhancePlugin function.

mdEnhancePlugin({
    card: true,
    container: true,
    footnote: true,
    include: true,
    mermaid: true,
    playground: true,
    tabs: true,
    tasklist: true,
    vuePlayground: true,
}),