Combine VuePress and Bootstrap to create a docs site and deploy it to Netlify
Tags: vue, webdev, vuepress, javascript
Published: 2021-03-23 19:16:36

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](https://vuepress.vuejs.org/), write your docs with a pinch of [Bootstrap](https://getbootstrap.com/docs/4.6/getting-started/introduction/) HTML and finally publish it to [Netlify](https://www.netlify.com/) using Netlify's GitHub integration.

**Let's go!**

### Install VuePress
The first thing we need to do is install VuePress.
```console
npm install --save-dev vuepress
```
and Bootstrap
```console
npm install bootstrap
```
### 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
```

### Add entries to package.json
For facilitating developing and building our docs site, add these two commands inside the `.package.json` `scripts` attribute
```json
  "scripts": {
    ...
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
```

### 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](https://vuepress.vuejs.org/theme/default-theme-config.html#navbar) and [sidebar](https://vuepress.vuejs.org/theme/default-theme-config.html#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.

```js
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']
        ]
      }
    ]
  }
}
```
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`
```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
```

> Note: Instead of importing the whole Bootstrap library you can include individual components instead, by importing them directly from `node_modules`, for example:
```scss
@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';
...
```
**We now have to import out .scss file**
The `enhanceApp.js` file is used to add [app-level enhancements](https://v1.vuepress.vuejs.org/guide/basic-config.html#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.
```js
import './styles/styles.scss';
```
 
**We are now ready to test our setup**
Open the main `README.md` in the docs folder and paste the following
```html
### 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>
```
then start the docs dev process.
```console
npm run docs:dev
```
Open your browser on `http://localhost:8080`, if all went well we should be now able to view our docs site.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8cbh9grtevc5w9tzqq7l.png)

### 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e1k710zp6w7ulmpp7g62.png)

- Then click on the GitHub button
![alt text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cljtx80x2s9tt31f5cw1.png)

- 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ndesqcpyqrgn2p686ctp.png)
Select the desired repositories and hit "Save".

- Back to the Netlify interface, pick the repository you wish to deploy.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rvsdbxhrm53mg1xx85y3.png)

- Fill in:
Branch to deploy: `master`
Build command: `vuepress build docs`
Publish directory: `public`
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7ok3njhblsdyb0zfggoi.png)
and hit "Deploy site"

- If you wish to change the site name you can do so from Netlify's domain management option.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/35q3akcrce76jrw7pqst.png)

**That's it!**

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