Vuepress is based on markdown files. Each HTML-page on the site has a corresponding markdown file in this repository.
Requirements and recommended tools
The following tools are required to build and develop the site.
- NodeJS (latest LTS) and the corresponding version of
The following tools will help you developing
- The vue-devtools
Setup / Commands
After cloning the repository you probaby want to run the following commands:
npm install(required) installs the dependencies libraries and is required for building the site.
npm run devruns a webpack-dev-server, usually on port 8080. This server features live-reloading. Styles will automatically be updated when you change the source files. Changes in markdown changes and Vue.js components will be visible immediately. Note that changes to the file
src/.vuepress/config.jsare not part of the live-reload and require a restart of the command.
npm run previewshould be run prior to creating a pull-request. It will clean the build-directories, run tests and linters, the site. A production-like preview of the site can be viewed at port 9080
Other commands are not needed as often:
npm run fixtrys to fix all
eslinterrors and runs
prettierto format everything. This is also done in a pre-commit hook so it should not be necessary to run this command manually.
npm run cleanremoves all cached and built files. This can be helpful if you have errors that you cannot explain and that just won't go away.
- The scripts
buildjust exist to make the other commands in the
Differences between dev-server and production
The Vuepress site is a Vue.js application. While the dev-server runs the whole application in the browser, the production site is pre-rendered with subsequent changes running in the browser.
Vue.js components that only work in the browser will work correctly in the dev-server, but will fail in production.
See Browser API Access Restrictions for details.
A few notes on the site and the build processes
- The site uses the Vuepress default-theme with a few custom styles.
- Markdown files in this repository automatically become HTML-files on the site.
Files and directories
src folder contains all sources of the page. That includes
src/**/*.md: Markdown files, one for each HTML files containing the actual content.
src/.vuepress/styles: stylus files that adjust the CSS styles of the website (TODO add documentation link)
src/.vuepress/components: custom Vue.js components and Layouts created for this site (TODO add documentation link)
src/.vuepress/public/: root directory for public files that are copied to the site as-is.
src/.vuepress/plugins/: Vuepress-plugins created for this site.
The deployment has two phases:
- The preview site at https://handlebars-draft.knappi.org is automatically updated when changes are pushed to the
master-branch. The Github-pages are hosted in the
gh-pages-branch of this repository.
- The production site (currently the temporary site https://handlebars-prod.knappi.org) is updated when changes are
pushed to the
production-branch. The Github-pages for the production site are hosted in the
master-branch of the docs-prod-ghpages repository.
In both cases, the deployment itself is performed via Travis-CI job
The Travis-CI job uses the handlebars-site-bot account to update the github-pages of this repository.