chore(hugo): Added devbox for hugo processing. Improved README documentation.
This commit is contained in:
parent
08847aac0a
commit
a845e0fcde
3 changed files with 177 additions and 24 deletions
73
README.md
73
README.md
|
|
@ -6,58 +6,83 @@ This repo contains business and architectural design and documentation of the De
|
|||
|
||||
The documentation is done in [Hugo-format](https://gohugo.io).
|
||||
|
||||
The repo contains a [Hugo `.devcontainer`-defintion](https://containers.dev/) so that you just have to run locally an IDE which is devcontainer aware, e.g. Visual Studio code.
|
||||
Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is
|
||||
|
||||
### Installation
|
||||
* either a Hugo [`.devcontainer`-definition](https://containers.dev/) - just run a devcontainer aware IDE or CLI, e.g. Visual Studio code
|
||||
* or a Hugo [`Devbox`-definition](https://www.jetify.com/devbox/) - in this case just run a devbox shell
|
||||
|
||||
To get a locally running documentation editing and presentation environment, follow these steps:
|
||||
## Local installation of the Hugo documentation system
|
||||
|
||||
We describe two possible ways (one with devcontainer, one with devbox) to get the Hugo-documentation system locally running.
|
||||
|
||||
For both prepare the following three steps:
|
||||
|
||||
1. open a terminal on your local box
|
||||
2. clone this repo: `git clone https://bitbucket.telekom-mms.com/scm/ipceicis/ipceicis-developerframework.git `
|
||||
3. change to the repo working dir: `cd ipceicis-developerframework`
|
||||
4. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`)
|
||||
5. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`)
|
||||
6. when the container is up & running just open your browser with `http://localhost:1313/`
|
||||
2. clone this repo: `git clone https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation`
|
||||
3. change to the repo working dir: `cd website-and-documentation`
|
||||
|
||||
If you want to run the devcontainer without VS Code, you can use npn to run it inside a docker container:
|
||||
### Possibility 1: Hugo in a devcontainer
|
||||
|
||||
1. install Node.js (>= Version 14), npm and the docker engine
|
||||
2. install the devcontainer cli: `npm install -g @devcontainers/cli`
|
||||
3. change into the folder of this repo
|
||||
4. start the devcontainer by running: `devcontainer up --workspace-folder .`
|
||||
5. find out the IP address of the devconatiner by using `docker ps` and `docker inspect <id of container>`
|
||||
6. when the container is up & running just open your browser with `http://<DOCKER IP>:1313/`
|
||||
[`devcontainers`](https://containers.dev/) are running containers as virtual systems on your local box. The defintion is in the `.devcontainer` folder.
|
||||
Thus as preliminary you need a container daemon running, e.g. Docker.
|
||||
|
||||
### Editing
|
||||
There are several options to create and run the devcontainer - we present here two:
|
||||
|
||||
#### Documentation language
|
||||
#### Option 1: Run the container triggered by and connected to an IDE, e.g. VS Code
|
||||
|
||||
1. open the repo in an [Devcontainer-aware tool/IDE](https://containers.dev/supporting) (e.g. `code .`)
|
||||
1. start the `devcontainer` (in VSC it's `F1 + Reopen in Devcontainer`)
|
||||
1. when the container is up & running just open your browser with `http://localhost:1313/`
|
||||
|
||||
#### Option 2: Run the container natively
|
||||
|
||||
An alternative to get the container image is the [devcontainer CLI](https://github.com/devcontainers/cli), then you can run the devcontainer without VS Code.
|
||||
Thus as preliminary you need to do the install steps of the devconatiner cli.
|
||||
|
||||
1. start the devcontainer by running: `devcontainer up --workspace-folder .`
|
||||
1. find out the IP address of the devconatiner by using `docker ps` and `docker inspect <id of container>`
|
||||
1. when the container is up & running just open your browser with `http://<DOCKER IP>:1313/`
|
||||
|
||||
### Possibility 2: Hugo in a devbox
|
||||
|
||||
[`Devboxes`](https://www.jetify.com/devbox/) are locally isolated environments, managed by the [Nix package manager](https://nix.dev/). So first [prepare the devbox](https://www.jetify.com/docs/devbox/installing_devbox/).
|
||||
|
||||
Then
|
||||
|
||||
1. ```devbox shell```
|
||||
1. In the shell: ```hugo serve```
|
||||
|
||||
|
||||
## Editing
|
||||
|
||||
### Documentation language
|
||||
|
||||
The documentation is done in [Docsy-Theme](https://www.docsy.dev/).
|
||||
|
||||
So for editing content just goto the `content`-folder and edit content arrording to the [Docsy documentation](https://www.docsy.dev/docs/adding-content/)
|
||||
|
||||
### Commiting
|
||||
## Commiting
|
||||
|
||||
After having finished a unit of work commit and push.
|
||||
|
||||
## Annex
|
||||
# Annex
|
||||
|
||||
### Installation steps illustrated
|
||||
## Installation steps illustrated
|
||||
|
||||
When you run the above installation, the outputs could typically look like this:
|
||||
|
||||
#### Steps 4/5 in Visual Studio Code
|
||||
### In Visual Studio Code
|
||||
|
||||
##### Reopen in Container
|
||||
#### Reopen in Container
|
||||
|
||||
|
||||
|
||||
##### Hugo server is running and (typically) listens to localhost:1313
|
||||
#### Hugo server is running and (typically) listens to localhost:1313
|
||||
|
||||
After some installation time you have:
|
||||
|
||||
|
||||
|
||||
#### Steps 6 in a web browser
|
||||
### Final result in a web browser
|
||||
|
||||
|
||||
|
|
|
|||
11
devbox.json
Normal file
11
devbox.json
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
{
|
||||
"$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.5/.schema/devbox.schema.json",
|
||||
"packages": [
|
||||
"hugo@0.125.4",
|
||||
"dart-sass@1.75.0"
|
||||
],
|
||||
"shell": {
|
||||
"init_hook": [],
|
||||
"scripts": {}
|
||||
}
|
||||
}
|
||||
117
devbox.lock
Normal file
117
devbox.lock
Normal file
|
|
@ -0,0 +1,117 @@
|
|||
{
|
||||
"lockfile_version": "1",
|
||||
"packages": {
|
||||
"dart-sass@1.75.0": {
|
||||
"last_modified": "2024-05-03T15:42:32Z",
|
||||
"resolved": "github:NixOS/nixpkgs/5fd8536a9a5932d4ae8de52b7dc08d92041237fc#dart-sass",
|
||||
"source": "devbox-search",
|
||||
"version": "1.75.0",
|
||||
"systems": {
|
||||
"aarch64-darwin": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/6ynzjs0v55h88ri86li1d9nyr822n7kk-dart-sass-1.75.0",
|
||||
"default": true
|
||||
},
|
||||
{
|
||||
"name": "pubcache",
|
||||
"path": "/nix/store/f4wbni4cqdhq8y9phl6aazyh54mnacz7-dart-sass-1.75.0-pubcache"
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/6ynzjs0v55h88ri86li1d9nyr822n7kk-dart-sass-1.75.0"
|
||||
},
|
||||
"aarch64-linux": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/g88isq3r0zpxvx1rzc86dl9ny15jr980-dart-sass-1.75.0",
|
||||
"default": true
|
||||
},
|
||||
{
|
||||
"name": "pubcache",
|
||||
"path": "/nix/store/l6vdyb4i5hb9qmvms9v9g7vsnynfq0lb-dart-sass-1.75.0-pubcache"
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/g88isq3r0zpxvx1rzc86dl9ny15jr980-dart-sass-1.75.0"
|
||||
},
|
||||
"x86_64-darwin": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/h79n1apvmgpvw4w855zxf9qx887k9v3d-dart-sass-1.75.0",
|
||||
"default": true
|
||||
},
|
||||
{
|
||||
"name": "pubcache",
|
||||
"path": "/nix/store/bxmfb2129kn4xnrz5i4p4ngkplavrxv4-dart-sass-1.75.0-pubcache"
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/h79n1apvmgpvw4w855zxf9qx887k9v3d-dart-sass-1.75.0"
|
||||
},
|
||||
"x86_64-linux": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/yvr71pda4bm9a2dilgyd77297xx32iad-dart-sass-1.75.0",
|
||||
"default": true
|
||||
},
|
||||
{
|
||||
"name": "pubcache",
|
||||
"path": "/nix/store/h8n6s7f91kn596g2hbn3ccbs4s80bm46-dart-sass-1.75.0-pubcache"
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/yvr71pda4bm9a2dilgyd77297xx32iad-dart-sass-1.75.0"
|
||||
}
|
||||
}
|
||||
},
|
||||
"hugo@0.125.4": {
|
||||
"last_modified": "2024-04-27T02:17:36Z",
|
||||
"resolved": "github:NixOS/nixpkgs/698fd43e541a6b8685ed408aaf7a63561018f9f8#hugo",
|
||||
"source": "devbox-search",
|
||||
"version": "0.125.4",
|
||||
"systems": {
|
||||
"aarch64-darwin": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/2ssds5l4s15xfgljv2ygjhqpn949lxj4-hugo-0.125.4",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/2ssds5l4s15xfgljv2ygjhqpn949lxj4-hugo-0.125.4"
|
||||
},
|
||||
"aarch64-linux": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/nln80v8vsw5h3hv7kihglb12fy077flb-hugo-0.125.4",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/nln80v8vsw5h3hv7kihglb12fy077flb-hugo-0.125.4"
|
||||
},
|
||||
"x86_64-darwin": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/n6az4gns36nrq9sbiqf2kf7kgn1kjyfm-hugo-0.125.4",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/n6az4gns36nrq9sbiqf2kf7kgn1kjyfm-hugo-0.125.4"
|
||||
},
|
||||
"x86_64-linux": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/k53ijl83p62i6lqia2jjky8l136x42i7-hugo-0.125.4",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/k53ijl83p62i6lqia2jjky8l136x42i7-hugo-0.125.4"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue