Skip to content

blech-lang/blech-doc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Blech documentation

Project Status: Active – The project has reached a stable, usable state and is being actively developed. Slack chat

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

  • Hugo, the static website generator,
  • Docsy, the Hugo documentation theme,

Installing the tool chain for this repository

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 Hugo - the static site generator

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.

Working 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

Install local npm modules

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

Preview the website

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/

Publish the static website content

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:

Check for broken links on the website

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.

Creating content

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.

About

Documentation for the Blech embedded programming language

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages