mdbook rust github pages A Step by Step Guide to Publishing Your Docs

Author

Reads 288

corrugatted metal
Credit: pexels.com, corrugatted metal

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

Credit: youtube.com, How to Create a Blog from Markdown files and publish it using GitHub Pages

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

Credit: youtube.com, How to Publish Rust Package/Crates Docs to GitHub Pages

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.

Credit: youtube.com, CI/CD Tutorial using GitHub Actions - Automated Testing & Automated Deployments

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

Credit: youtube.com, Creating a website on GitHub pages with mdBook

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.

Jennie Bechtelar

Senior Writer

Jennie Bechtelar is a seasoned writer with a passion for crafting informative and engaging content. With a keen eye for detail and a knack for distilling complex concepts into accessible language, Jennie has established herself as a go-to expert in the fields of important and industry-specific topics. Her writing portfolio showcases a depth of knowledge and expertise in standards and best practices, with a focus on helping readers navigate the intricacies of their chosen fields.

Love What You Read? Stay Updated!

Join our community for insights, tips, and more.