Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
84 lines (57 sloc) 4.24 KB

Development setup

This site uses Vuepress as static page generator. It is a static page generator based on vue.js and created to write the documentation of that framework.

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 npm

The following tools will help you developing

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 dev runs 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.js are not part of the live-reload and require a restart of the command.
  • npm run preview should 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 fix trys to fix all eslint errors and runs prettier to format everything. This is also done in a pre-commit hook so it should not be necessary to run this command manually.
  • npm run clean removes 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 test,lint, format and build just exist to make the other commands in the package.json more readable.

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

The 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.

Deployment

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.

You can’t perform that action at this time.