DEV Community

loading...
Cover image for Combine VuePress and Bootstrap to create a docs site and deploy it to Netlify

Combine VuePress and Bootstrap to create a docs site and deploy it to Netlify

Giannis Koutsaftakis
Frontend developer, passionate about all things web
Updated on ・5 min read

VuePress is great for writing and publishing docs for your project. You write Markdown files which are then converted to prerendered static HTML pages by the VuePress engine. One of its great strengths is that you can mix Markdown, HTML, and Vue components inside your .md files to create a better documentation experience.

In this article, we'll cover how you can install VuePress, write your docs with a pinch of Bootstrap HTML and finally publish it to Netlify using Netlify's GitHub integration.

Let's go!

Install VuePress

The first thing we need to do is install VuePress.

npm install --save-dev vuepress
Enter fullscreen mode Exit fullscreen mode

and Bootstrap

npm install bootstrap
Enter fullscreen mode Exit fullscreen mode

Create the docs folder

We'll then create our folder in which our documentation is going to be stored. Go ahead and create a docs folder in your project's root. Documentation is written in Markdown .md files. Inside the docs folder, create a README.md (or index.md) file. This is going to be the documentation site's index, the home page.

You can organize your .md files in subfolders as well.

Create the .vuepress folder

Now for the VuePress config folder. Create a new directory .vuepress inside the docs folder with the following structure

├── docs
│   ├── .vuepress
│   │   ├── styles
│   │   │   ├── styles.scss <-- Bootstrap styles will go here
│   │   ├── config.js <-- Vuepress config file
│   │   └── enhanceApp.js <-- We'll load the styles.scss file here
│   │ 
│   ├── README.md
└── package.json
Enter fullscreen mode Exit fullscreen mode

Add entries to package.json

For facilitating developing and building our docs site, add these two commands inside the .package.json scripts attribute

  "scripts": {
    ...
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
Enter fullscreen mode Exit fullscreen mode

VuePress config

The config.js file is used for setting various configuration options for our docs site such as e.g title, description, etc. Other options include customizing the main navigation and sidebar, as well as adding tags to the head of the site. We'll just use a minimal example setup here as detailed nav and sidebar configs are out of the scope of this article. Just be sure to set the dest attribute as we'll need it later for our deployment.

module.exports = {
  title: 'My project',
  description: 'A demo setup for VuePress',
  dest: 'public',
  themeConfig: {
    nav: [
      { text: 'Github', link: 'https://github.com/myproject' }
    ],
    sidebar: [
      ['/', 'Introduction'],
      ['/installation/', 'Installation'],
      {
        title: 'Examples',
        collapsable: true,
        children: [
          ['/examples/example1/', 'Example 1'],
          ['/examples/example2/', 'Example 2']
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Here, as an example, we created a GitHub link for our project on the navbar and three entries for the sidebar: Introduction, Installation, and Examples.

For each of the children array entries inside the sidebar array, VuePress looks for a README.md or an index.md inside the designated folder and sets the relevant title.
For example, VuePress will create a sidebar entry named "Installation" including the contents of the /installation/index.md file.

The "Examples" entry is a little special in the way that we manually create collapsable children for the "Examples" sidebar entry. This is useful when we don't want our page links to occupy a lot of space in the sidebar.

Add Bootstrap

We'll use the styles.scss file to add the Bootstrap CSS. Since VuePress already contains global CSS this is the place that we can add our own SCSS variables and overrides rules so that Bootstrap components display as they should.
Here's an example styles.scss

@import '~bootstrap/scss/bootstrap';

$primary: #3eaf7c !default;
$link-color: $primary !default;
$link-hover-color: lighten($link-color, 15%) !default;

/* Content width fix */
.theme-default-content:not(.custom) {
  box-sizing: content-box;
}

/* Table width fix */
table.table {
  display: table;
}

// Add more CSS here
Enter fullscreen mode Exit fullscreen mode

Note: Instead of importing the whole Bootstrap library you can include individual components instead, by importing them directly from node_modules, for example:

@import '~bootstrap/scss/_functions';
@import '~bootstrap/scss/_variables';
@import '~bootstrap/scss/_mixins';
@import '~bootstrap/scss/_root';
@import '~bootstrap/scss/_reboot';
@import '~bootstrap/scss/_type';
@import '~bootstrap/scss/_images';
@import '~bootstrap/scss/_code';
@import '~bootstrap/scss/_grid';
@import '~bootstrap/scss/_tables';
@import '~bootstrap/scss/_forms';
@import '~bootstrap/scss/_buttons';
...
Enter fullscreen mode Exit fullscreen mode

We now have to import out .scss file
The enhanceApp.js file is used to add app-level enhancements such as making Vue components globally available. In this case, though we're only going to use it to import our Bootstrap styles.

Open enhanceApp.js and import the styles.scss file.

import './styles/styles.scss';
Enter fullscreen mode Exit fullscreen mode

We are now ready to test our setup
Open the main README.md in the docs folder and paste the following

### This is a bootstrap table

<div>
  <table class="table">
    <thead class="thead-dark">
      <tr>
        <th scope="col">#</th>
        <th scope="col">First</th>
        <th scope="col">Last</th>
        <th scope="col">Handle</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row">1</th>
        <td>Mark</td>
        <td>Otto</td>
        <td>@mdo</td>
      </tr>
      <tr>
        <th scope="row">2</th>
        <td>Jacob</td>
        <td>Thornton</td>
        <td>@fat</td>
      </tr>
    </tbody>
  </table>
</div>
Enter fullscreen mode Exit fullscreen mode

then start the docs dev process.

npm run docs:dev
Enter fullscreen mode Exit fullscreen mode

Open your browser on http://localhost:8080, if all went well we should be now able to view our docs site.
Alt Text

Deploy to Netlify

Netlify makes it really easy to deploy our docs site. We just need to connect our GitHub repo and configure our public folder and site name.

  • Login to Netlify and click on the "New site from Git" button
    Alt Text

  • Then click on the GitHub button
    alt text

  • You'll be asked to install Netlify to your GitHub account. After you do that you can select which repositories Netlify will have access to.
    Alt Text
    Select the desired repositories and hit "Save".

  • Back to the Netlify interface, pick the repository you wish to deploy.
    Alt Text

  • Fill in:
    Branch to deploy: master
    Build command: vuepress build docs
    Publish directory: public
    Alt Text
    and hit "Deploy site"

  • If you wish to change the site name you can do so from Netlify's domain management option.
    Alt Text

That's it!

Our docs site is now published and available on the internet 🚀.

Discussion (0)

Forem Open with the Forem app