Documentation for the Blech embedded programming language. Read the documentation on blech-lang.org
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.
Clone this repository:
git clone https://github.com/blech-lang/blech-doc.git
The Blech documentation uses the Docsy theme as a Hugo module. For more information see the Docsy Getting Started Documentation.
To update the Docsy theme go to the website subfolder in your cloned repository.
cd blech-doc/website
Invoke Hugo’s module get subcommand with the update flag
hugo mod get -u github.com/google/docsy
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
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/
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 main 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:
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://blech-lang.org -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.