# Website Developer Guide
This guide describes all steps required to build the website at https://www.asterics.eu (opens new window).
# Requirements
Following tools need to be setup on your machine:
# Get Started
To build the website, execute following steps:
~ $ git clone https://github.com/asterics/asterics-docs.git
~ $ cd asterics-docs
~/asterics-docs $ yarn
Note
asterics-docs
(opens new window) contains three branches with predefined roles:
master
: branch used to build release at https://www.asterics.eu (opens new window).next
: branch used to build releast at https://www.asterics.eu/next/ (opens new window).gh-pages
: branch containing both releases.
After executing these steps, the main repository is cloned and all required packages are installed.
TIP
Consider cloning asterics-docs
(opens new window) inside a folder, that contains other AsTeRICS repostories for faster cloning of submodules (cf. parameter reference).
For the next steps, we have to use commands provided by @asterics-docs/tool
, which includes cloning all repositories containing documentation for https://www.asterics.eu (opens new window).
The configuration for @asterics-docs/tool
is stored in docs.config.js
(see Configuration for details).
~/asterics-docs $ yarn docs init # @asterics-docs/tool docs init
~/asterics-docs $ yarn docs setup # @asterics-docs/tool docs setup
These steps will clone all repositories and copy specified files in a single folder, which is used to build the website.
~/asterics-docs $ yarn dev # Start the development server
~/asterics-docs $ yarn build # Build for deployment
After executing the last step, you can locate the finished build in folder dist/
.
# @asterics-docs/tool
To install @asterics-docs/tool
inside a project, run following command.
For npm run:
$ npm install @asterics-docs/tool # local installation
$ npm install -g @asterics-docs/tool # global installation
For yarn run:
$ yarn add @asterics-docs/tool # local installation
$ yarn add global @asterics-docs/tool # global installation
Aftwards you can run @asterics-docs/tool
:
$ npx asterics-docs --help # local installation
$ asterics-docs --help # global installation
# Commands
asterics-docs/tool
and supported commands provide a detailed help on parameters and options.
$ npx asterics-docs -h # @asterics-docs/tool help instruction
$ npx asterics-docs <command> -h # @asterics-docs/tool command help instruction
The package.json
(opens new window) of asterics-docs
contains a script to run @asterics-docs/tool
.
Thus, the above commands can be expressed as follows (inside asterics-docs
(opens new window)):
$ yarn docs -h # @asterics-docs/tool help instruction
$ yarn docs <command> -h # @asterics-docs/tool command help instruction
# init
Clone all submodules of asterics-docs
.
$ asterics-docs init # global installation
$ yarn docs init # inside asterics-docs
$ yarn docs init --help
asterics-docs init
Options:
-h, --help Show this help.
-c, --config Path to configuration file.
--reference Pull git submodules from remote (use --no-reference).
# clean
Delete all submodules of asterics-docs
.
$ asterics-docs clean # global installation
$ yarn docs clean # inside asterics-docs
$ yarn docs clean --help
asterics-docs clean
Options:
-h, --help Show this help.
-c, --config Path to configuration file.
# setup
Copy all files according to the configuration (see configuration parameter source
and sources
).
$ asterics-docs setup # global installation
$ yarn docs setup # inside asterics-docs
$ yarn docs setup --help
asterics-docs setup
Options:
--version Show version number.
-h, --help Show this help.
-c, --config Path to configuration file.
-v, --verbose Print all entries.
# index
Show information on entry inside the source directory of asterics-docs
(e.g., configuration, conflicts).
$ asterics-docs index # global installation
$ yarn docs index README.md # inside asterics-docs
$ yarn docs index --help
asterics-docs index [path]
Positionals:
path a path of the index
Options:
-h, --help Show this help.
-c, --config Path to configuration file.
--conflicts Show conflicting entries.
--silent Do not print indexed paths.
# status
Show status of source directory of asterics-docs
.
$ asterics-docs status # global installation
$ yarn docs status # inside asterics-docs
$ yarn docs status -h
asterics-docs status
Options:
-h, --help Show this help.
-c, --config Path to configuration file.
# add
Stage changes inside the source directory of asterics-docs
.
$ asterics-docs add <file> # global installation
$ yarn docs add <file> # inside asterics-docs
$ yarn docs add --help
asterics-docs add <file>
Positionals:
file File/folder to add.
Options:
-h, --help Show this help.
-c, --config Path to configuration file.
DANGER
Commiting can only be done per repository.
Creating new files inside asterics-docs
is currently not supported.
If you need to create new files, you have to copy those files manually or create them before running yarn docs setup
.
Please don’t stage changes of different repositories at the same time or new files.
# commit
Commit changes inside the source directory of asterics-docs
and source repository.
$ asterics-docs commit <submodule> <message> # global installation
$ yarn docs commit <submodule> <message> # inside asterics-docs
$ yarn docs commit --help
asterics-docs commit <submodule> <message>
Positionals:
submodule Submodule selected for commit.
message Commit message.
Options:
-h, --help Show this help.
-c, --config Path to configuration file.
# push
Push submodule changes to remote repository.
$ asterics-docs push [submodule] [branch] # global installation
$ yarn docs push [submodule] [branch] # inside asterics-docs
asterics-docs push [submodule] [branch]
Positionals:
submodule Submodule selected for update.
branch Branch of submodule to be updated (with rebase).
Options:
--version Show version number.
-h, --help Show this help.
-c, --config Path to configuration file.
TIP
Specifying no submodule, results in all branches of all submodules beeing updated.
Specifying both submodule and branch, results in a pull (with rebase) followed by a push of specified branch.
# Configuration
# base
- Type:
string
- Default:
null
- Example:
/
The base URL the site will be deployed at.
You will need to change this if you plan to deploy your site under a sub path.
If you plan to deploy your site to https://www.asterics.eu/next/
, then you should set base
to "/next/"
.
# port
- Type:
number
- Default:
null
- Example:
8080
Specify the port to use fot the dev server.
# source
- Type:
string
- Default:
null
- Example:
docs
Specify the output directory of @asterics-docs/tool
or input directory for vuepress
.
Relative paths are resolved based on the result of process.cwd()
.
# dest
- Type:
string
- Default:
null
- Example:
dist
Specify the output directory for vuepress build
.
Relative paths are resolved based on the result of process.cwd()
.
# host
- Type:
string
- Default:
null
- Example:
https://www.asterics.eu
Specify the host were page it deployed to.
# versions
- Type:
array
- Default:
null
- Example:
["4.0", "3.0.1", "3.0", "2.8", "2.7", "2.6", "2.5", "2.3"]
Specify the version you want to build. First entry is always the current version and is not sub-pathed as others.
# sources
- Type:
array
The definition of sourcesConfig
is as follows:
interface normalSourcesConfig {
repository: string; // name of repository in .gitmodules
reference: string; // reference location of git repository
files: [filesConfig]; // file dependencies of submodule (for asterics-docs)
}
interface filesConfig {
source: string; // source location (folder/file)
destination: string; // target destination (asterics-docs)
filter: regexp; // regular expression for paths to include
exclude: regexp; // regular expression for paths to exclude
branch: string; // branch containing the required files, or
versions: [string, string]; // version map, specifying branches for each version ([version, branch])
}
type sourceConfig = normalSourcesConfig;