Creating a markdown book

[tjayrush]

Description

Set up an mdBook to generate a documentation website for this repository, similar to reth.rs. The book should be easily maintainable and deployable to GitHub Pages or another hosting platform.

---

Task List

1. Install mdBook

• Install mdBook on your system using the Rust package manager:

  cargo install mdbook

• If Rust is not installed, install it first:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Verify installation:

  mdbook --version

2. Initialize the Book

• Navigate to the repository folder:

  cd /path/to/your/repo

• Initialize the mdBook structure:

  mdbook init book

• This will create a folder book with the following structure:

  book/
  ├── book.toml       # Configuration file
  ├── src/
      ├── SUMMARY.md  # Table of contents
      ├── index.md    # Home page
      ├── <other files>.md
  

3. Customize the Book

• Open book/book.toml and update the metadata:

  [book]
  title = "My Awesome Book"
  authors = ["Your Name"]
  description = "A book for my awesome project."

• Edit book/src/SUMMARY.md to define the structure of the book:

  # Summary
  
  - [Introduction](index.md)
  - [Getting Started](getting_started.md)
  - [Usage](usage.md)
  - [API Reference](api_reference.md)

4. Add Content

• Add your Markdown files to book/src/ (e.g., getting_started.md, usage.md).
• Populate them with your documentation content.

5. Build the Book

• Generate the static HTML files:

  mdbook build

• Serve the book locally for preview:

  mdbook serve

• Open http://localhost:3000 in your browser to view the book.

6. Deploy the Book

• Deploy the book/build/ folder to GitHub Pages or another hosting platform.

GitHub Pages Deployment

1. In your repository, go to Settings > Pages.
2. Select the branch and folder where book/build/ is located (e.g., gh-pages or /docs).
3. Push the contents of book/build/ to the selected branch.

Automate Deployment with GitHub Actions

• Use the following workflow to automate deployment:

  name: Deploy Book
  on:
    push:
      branches:
        - main
  
  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
        - name: Build mdBook
          run: mdbook build
        - name: Deploy to GitHub Pages
          uses: peaceiris/actions-gh-pages@v3
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./book/build

7. Maintain and Update

• To update the book:
  1. Modify Markdown files in book/src/.
  2. Rebuild the book using mdbook build.
  3. Push updated book/build/ to the hosting branch or re-run your CI pipeline.

---

Acceptance Criteria:

• A book/ folder is created with the proper structure.
• The book can be built and previewed locally.
• The book is deployed and accessible via GitHub Pages or another hosting platform.
• Documentation updates are easy to maintain and deploy.