Documentation for the Blech embedded programming language. Read the documentation on the new homepage.
If you want to change the contents of that website read the following to get started.
The necessary tool chain to build the documentation and the website consists of
On windows we recommend Chocolatey for the installation of Hugo.
For chocolatey we recommend the non-administrative install. In a corporate setup behind a proxy use the corresponding options.
From time to time run an upgrade.
choco upgrade chocolatey
Install the extended version of Hugo. The extended version is necessary for the Docsy theme.
Details can be found in the Hugo Installation documentation
On windows we recommend to install Hugo with Chocolatey.
choco install hugo-extended -confirm
Test it
hugo version
You should see /extented behind the version number.
Now you are ready to work with the repository.
The Blech documentation already contains the Docsy theme as a git submodule. For more information see the Docsy Getting Started Documentation. Therefore clone in the following way:
git clone --recurse-submodules --depth 1 https://github.com/boschresearch/blech-doc.git
You need to install the following npm modules locally to the /website directory of the repository. You must have a recent version of NodeJS installed on your machine to use npm.
npm is frequently updated. In order to keep up-to-date run:
npm install npm@latest -g
To install the necessary npm modules go to the website subfolder in your cloned repository.
cd blech-doc/website
Locally install the npm modules autoprefixer, postcss-cli and postcss.
npm install -D autoprefixer
npm install -D postcss-cli
npm install -D postcss
The Hugo Docsy theme is frequently updated. From time to time update the Docsy theme submodule.
From the root of your repository run:
git submodule update --remote
Change to the ./website subdirectory.
cd website
Run the website without static site generation
hugo server
Use options -D and -F to preview draft and future content:
hugo -D -F server
Open the Blech site preview: http://localhost:1313/blech-doc
The static website content is generated into the /docs folder of the repository. In order to get a clean content, we recommend to delete the /docs folder before creating the content.
From top of the repository run
rm -r docs
The content can be generated from the commandline.
Change to subfolder ./website/scripts.
cd website/scripts
and run
./build.[sh, bat]
The website is deployed as a GitHub Project Page. For simplicity, we deploy the project pages from the /docs folder on the master branch
For publishing just push the content of the /docs folder to the master branch.
Give GitHub some time to deploy the content and open the Blech site on https://boschresearch.github.io/blech-doc
In order to check the links on the website you can use the npm package broken link checker.
Install it with
npm install broken-link-checker -g
Test the installation
blc --help
Check the whole Blech website with
blc https://boschresearch.github.io/blech-doc -ro
The last command only works in a network with commandline DNS access, i.e. without a proxy.
The documentation for the Docsy Theme explains how to create content.
Creating a blog post is easy. The Docsy example site shows how to do this.