
So, you've written your documentation in mdbook and you want to publish it on GitHub Pages. Sounds like a plan! First, you need to create a new GitHub repository for your project.
To start, you'll need to install the mdbook command-line tool using Cargo, Rust's package manager. This will allow you to build and serve your documentation locally.
Create a Blog
To create a blog with mdbook, start by running mdbook init example in the folder you want to use for your project. This will initialise a new project.
The book folder is where you'll find the auto-generated files after you run mdbook build. This is also the folder you'll publish with Github Pages later.
The book.toml file holds the properties of your blog, such as the title and author. You can find more information on how to use this file by following the instructions provided by mdbook.
Mdbook generates the entire book as static HTML, which you can then send to the server using sftp, ftp, scp, or rsync.
If this caught your attention, see: See Website Archive
Publish Our Blog
To publish our blog, we first need to set up a GitHub Action to automatically build and deploy our blog. This is because we haven't set up the necessary action to build and deploy our blog yet.
Navigate to the settings tab, then click Pages and change the source option to GitHub Actions. Choose the configure button right below the source section, and click Commit Changes two times. This will enable the GitHub Action to build and deploy our blog automatically whenever we push our code to the repository.
After setting up the GitHub Action, we need to upload the generated static website files to our web server or static hosting platform, such as GitHub Pages. To do this, we need to build the final static website files using the command `mdbook build`. This will generate a folder named "dist" that contains the generated HTML, CSS, JavaScript, and other files.
Here's an interesting read: Blog Web Page Design
Once we have the "dist" folder, we can upload it to GitHub Pages by clicking on "Settings" and finding "Pages" inside. Then, we click on "Build and Deployment" and choose GitHub Actions as the source. After committing the code, we wait for GitHub Actions to finish running, and we will have our own website homepage.
GitHub and Automation
GitHub Actions can be a powerful tool for automating tasks, and mdBook is no exception. The rust-lang/mdBook Setup Action allows us to run mdBook on a virtual machine hosted on GitHub Actions.
This action supports Linux, macOS, and Windows, making it a versatile option for developers. You can choose from ubuntu-20.04, ubuntu-22.04, macos-latest, and windows-2019 as the operating system to run your mdBook project on.
Here's a breakdown of the supported operating systems and their status:
Update to Latest Version
Updating to the latest version of mdBook is a straightforward process. You can set `mdbook-version: 'latest'` to fetch the latest version from the mdBook Homebrew Formulae.
Using the latest version of mdBook ensures you have the most recent features and security patches. This is especially important for a tool like mdBook that's used to build and maintain documentation.
To sync the mdBook version between a Docker Compose and a GitHub Actions workflow, you can use a `.env` file. This allows you to keep your version control consistent across different environments.
GitHub Actions
GitHub Actions is a powerful tool that allows you to automate your workflows on GitHub. It's incredibly useful for tasks like deploying your GitHub Pages.
You can create a workflow file, like .github/workflows/gh-pages.yml, to specify the actions you want to take. For example, you can use the peaceiris/actions-gh-pages action to deploy your GitHub Pages for the first time.
To run your workflow, you'll need to specify the operating system you want to use, such as ubuntu-20.04 or macos-latest.
Here are the supported operating systems for GitHub Actions:
You can also use GitHub Actions to run mdBook on a virtual machine. The rust-lang/mdBook Setup Action supports Linux, macOS, and Windows.
Tips
For mdbook, you can use the Alpine base Docker image provided by peaceiris on the Docker Hub repository at peaceiris/docker-mdbook: mdBook Alpine Base Docker Image.
Featured Images: pexels.com


