tfgrid/info_tfgrid
30
3
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Activity

development #41

Merged
mik-tf merged 6 commits from development into main 2024-04-27 14:09:19 +00:00
Conversation 0 Commits 6 Files Changed 1 +177
1 changed files with 177 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 5c87340c67 - Show all commits

177
docs/hero_create_mdbook.md Normal file
View File

@ -0,0 +1,177 @@
<h1>Create a New mdbook with Hero</h1>
<h2>Table of Contents</h2>
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Creating a New mdbook](#creating-a-new-mdbook)
- [Cloning the mdbook Repository](#cloning-the-mdbook-repository)
- [Directory Tree Example](#directory-tree-example)
- [Files and Directories Example](#files-and-directories-example)
- [Generating the mdbook Locally](#generating-the-mdbook-locally)
- [Pushing the Changes](#pushing-the-changes)
- [Generating the mdbook from a Remote Repository](#generating-the-mdbook-from-a-remote-repository)
***
## Introduction
We show how to build an mdbook using the [Hero tool](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero).
For this guide, we will show how to add an mdbook to the TFGrid repository `info_tfgrid` on `git.ourworld.tf`.
## Prerequisites
Before proceeding further, make sure you read and completed the [guide on how to use Hero and mdbook](./hero_fullvm.md).
## Creating a New mdbook
Let's go through all the steps to create a new mdbook. We will call our book `new_mdbook`.
### Cloning the mdbook Repository
For this guide, we will add a book to `info_tfgrid`. For this reason, we first start to clone the repository. Note that this step can be done automatically by Hero, but it might be easier to do it manually for later steps, such as pushing changes with git.
```
mkdir -p /root/code/git.ourworld.tf/tfgrid
cd /root/code/git.ourworld.tf/tfgrid
git clone https://git.ourworld.tf/tfgrid/info_tfgrid
```
Once we've cloned the repository, we can make changes to the repository and then push it to `git.ourworld.tf` when we're ready.
Before creating the new mdbook, let's have a look at how the overall directory tree will look like.
### Directory Tree Example
We first show the directory tree template to give an overview of the project. Without taking into account the other mdbooks within the repository, the overall directory tree would look like this:
```
├── books
│ └── new_mdbook
│ ├── SUMMARY.md
│ └── sync_production.sh
├── collections
│ └── new_mdbook
│ ├── .collection
│ ├── new_mdbook_example1.md
│ └── new_mdbook_example2.md
└── heroscript
└── new_mdbook
├── book_collections.md
├── context.md
└── sshkey.md
```
### Files and Directories Example
Hero uses three main directories to build an mdbook `books`, `collections` and `heroscript`. Let's have a look at each of them.
- `books`
- This directory contains the file `SUMMARY.md` of every mdbook as well as a script file called `sync_production.sh`. Each summary file is within the proper mdbook directory (here we have `new_mdbook`).
- In our case, we will have `books/new_mdbook/SUMMARY.md`.
- The summary file will point to the markdown files we want our mdbook populated with.
- We note that the SUMMARY.md file needs to point to a directory contained within the `collections` directory, as shown just below.
```
- [Example 1](new_mdbook/new_mdbook_example1.md)
- [Example 2](new_mdbook/new_mdbook_example2.md)
```
- The script file named `sync_production.sh` should contain the following content (make sure to adjust with the proper book name):
```
#!/bin/bash
rsync -rv ~/hero/www/info/new_mdbook/ root@info.ourworld.tf:/root/hero/www/info/new_mdbook/
```
- `collections`
- This directory contains all the markdown files needed to build all the books in the repository.
- In our case, we will put two markdown files in the new collections named `new_mdbook`
- `collections/new_mdbook/new_mdbook_example1.md`
- `collections/new_mdbook/new_mdbook_example2.md`
- Note that each collections directory should contain a file called `.collection`. This file should be empty.
```
touch .collection
```
- `heroscript`
- This directory contains three files that are necessary for Hero to build the mdbook, `book_collections.md`, `context.md` and `sshkey.md`
- `context.md` sets the proper configuration for the mdbook using the command `configure`
- This file is the same throughout all the `info_tfgrid` repository.
```
!!books.configure
buildroot:'~/hero/var/mdbuild'
publishroot:'~/hero/www/info'
install:true
reset:false
```
- `sshkey.md` contains the private SSH key
- This file is the same throughout all the `info_tfgrid` repository.
```
!!sshagent.key_add
name:'books'
privkey:'
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
QyNTUxOQAAACDXf9Z/2AH8/8a1ppagCplQdhWyQ8wZAieUw3nNcxsDiQAAAIhb3ybRW98m
0QAAAAtzc2gtZWQyNTUxOQAAACDXf9Z/2AH8/8a1ppagCplQdhWyQ8wZAieUw3nNcxsDiQ
AAAEC+fcDBPqdJHlJOQJ2zXhU2FztKAIl3TmWkaGCPnyts49d/1n/YAfz/xrWmlqAKmVB2
FbJDzBkCJ5TDec1zGwOJAAAABWJvb2tz
-----END OPENSSH PRIVATE KEY-----
'
```
- `book_collections.md` has many purposes
- It is used to generate the mdbook name
- It points the URL where the SUMMARY.md is located
- In the directory `books` as we've seen above
- It also point the URLs where the markdown files are located
- In the directory `collections` as we've seen above
```
!!book.generate name:'new_mdbook' title:'New mdbook'
url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/books/new_mdbook'
!!doctree.add
url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/collections/new_mdbook'
```
## Generating the mdbook Locally
Once you've created all the necessary files for your mdbook, you can build the mdbook locally with Hero:
```
hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook
```
Then you can open the mdbook locally:
```
hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook -o
```
If you're using a remote VM for Hero, you can run the following line to see the book on your local browser. Check the [Hero Full VM guide](./hero_fullvm.md) for more information on this.
```
pushd /root/hero/www/info/new_mdbook/; python3 -m http.server 5173; popd;
```
## Pushing the Changes
Once you've set the files and directories for your new mdbook and that you are satisfied with the result, you can push the changes to `git.ourworld.tf`.
```
git add .
git commit -m "added new book to info_tfgrid"
git push
```
## Generating the mdbook from a Remote Repository
Once the changes are uploaded to the remote repository, you will be able to update the local repository and build the new mdbook using the remote repository URL:
- Update the repository
```
hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook -gr
```
- Build the book
```
hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook -o
```