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
and Bootstrap
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
"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 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']
]
}
]
}
}
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
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';
...
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';
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>
then start the docs dev process.
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.
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
Then click on the GitHub button
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.
Select the desired repositories and hit "Save".Back to the Netlify interface, pick the repository you wish to deploy.
Fill in:
Branch to deploy:master
Build command:vuepress build docs
Publish directory:public
and hit "Deploy site"If you wish to change the site name you can do so from Netlify's domain management option.
That's it!
Our docs site is now published and available on the internet 🚀.
Top comments (0)