Step by step to publish mdBook in gh-pages

[TheRustifyer]

Hi there!

I am having troubles deploying the mdBook to GitHub-Pages.

I am not understand how should I link the deployed book to a URL in order to reach it via web browser.

Is out there some step-by-step` guide on how to correctly configurate an action to deploy it and serve it from gh-pages? Or the same but manually, without an action w'd be fine as well.

Sorry, it's my first time doing this and I am getting mad.

Thanks in advice!

[ehuss]

It isn't exactly step-by-step, but https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Pages should provide steps on how to publish to GitHub Pages. You'll need to double-check that pages are enabled in the Settings of your repo on GitHub. The settings page contains the URL for the site (https://rust-lang.github.io/mdBook/ for example).

[joshrotenberg]

To add to @ehuss's answer ...

I recently created a very basic mdbook for a presentation deployed to Github Pages via Github Actions: https://github.com/joshrotenberg/wtd-bayarea-mdbook

Take a look at the deploy.yml to see how it works. I'm happy to answer any questions you might have.

[ehuss]

I'm going to close as there is some documentation on how to do this on the wiki. If there is something missing, it is open for edits.

[kg4zow]

I have this working, and have added it to the template I use whenever I start a new documentation project.

https://github.com/kg4zow/mdbook-template

Note that the commands in Makefile use git worktree, which means you must be using git version 2.0.7 or later.

[ghost]

If I use @joshrotenberg 's example repo or @kg4zow 's example repo as suggested in this issue, I am only able to see the contents in the README.md file in the github pages and do not see the mdbook's content like it shows here from @joshrotenberg 's repo. I think I am possibly missing some commands I need to perform with respect to mdbook and/or github pages that are not explained either here or in the wiki. It will be helpful to have a step-by-step guide.

[kg4zow]

It sounds like you may be confused about what GitHub Pages actually is. GitHub Pages is a free add-on service which allows people to host static web sites, such as those generated using mdbook, on GitHub's servers. It requires that the "source code" of the web site be stored in a certain branch (usually called gh-pages) in a GitHub repo.

In the case of my template repo ...

• https://github.com/kg4zow/mdbook-template/ is the REPO containing the book's source code.

• https://kg4zow.github.io/mdbook-template/ is the GitHub Pages site containing the rendered output generated from that repo.

  ⚠️ This is explained at the top of the README.md file in the repo itself.

The gh-pages target in the repo's Makefile shows what running make gh-pages actually does under the covers, which is ...

• check out the gh-pages branch to a new "worktree" (an additional working directory tracked by the same .git/ directory)
• use mdbook build to render the book to the book/ directory
• use rsync to copy the rendered book's files over the additional "worktree"
• in that "worktree", commit the changes and push the gh-pages branch to GitHub
• delete the additional "worktree"

When GitHub sees the new commit on the gh-pages branch, it updates the web pages shown by the GitHub Pages service. This normally takes 5-10 seconds, but I've seen it take up to three minutes.

The README.md file in my template repo contains what I thought was a step-by-step guide.

• The "TL;DR" section at the top is for people like myself who are already familiar with how it works and just want a checklist. (I refer to this myself when starting new books.)
• The "Background" section explains what the various pieces are and how they work.
• The "Pre-Requisites" section explains what you'll need to have installed on your workstation before trying to use this stuff.
• The "Starting a new book from this repo" section originally explained how to start a new book, however I moved the content up to the "TL;DR" section and don't want to have to maintain two copies of the same information.
• The "Working on your book" section explains the day-to-day workflow of editing and publishing the book.

If something isn't explained clearly in the README.md file I welcome feedback, however I ask that you be specific about what you think is wrong and/or how it could be improved. (Or even better, this is GitHub, fork the repo and send me a pull request.) However, be aware that I'm not going to write directions for people to "just copy and paste", I want people to understand how stuff works so they don't need that kind of hand-holding.

You may also want to read through Eric Raymond's "How To Ask Question The Smart Way" as well.

[ghost]

@kg4zow : Thank you for the detailed explanation. Please see my response below.

GitHub Pages is a free add-on service which allows people to host static web sites, such as those generated using mdbook, on GitHub's servers. It requires that the "source code" of the web site be stored in a certain branch (usually called gh-pages) in a GitHub repo -- I knew that GitHub Pages is a free hosting service for static websites and the source code is the repo, but what I learned from this para is that the source code used to render the website is a different branch than the main branch. I didn't know that and was assuming that main branch is the source code used to render the front-end of the website. Thanks.

Further, I actually used the instructions from the template-repo you referred in your original response to the OP. I used VS Code in Windows when following those instructions, but I was getting errors for many of those commands that I believe are Linux-specific, particularly the make command besides others like -rf with rm (rm works, but without -rf). I had mdbook, Rust, GitHub CLI installed when I tried to follow those instructions. It could be that some of those commands may not work well in Windows and may prevent me to create all the files requires to create the source code for the website. Based on the information I shared, I am confused about the following two question:

1. I think where I am failing could be because I am using Windows and the make command may not work there (not sure, I might be wrong). Any suggestion?
2. In case I am able to run all the commands as you described in your template-repo, I believe I need to go to the settings-->Code and automation-->pages-->Branch: gh-pages and save that setting. Is that right?

Thank you again for the detailed response. I think it helped me learn something new, but I probably need to cross few hurdles described above to be able to get it to work.

[ghost]

@kg4zow I tried the steps in WSL and I didn't get the errors there. Thank you for those instructions and your help here.

[tylerdotrar]

I know this is closed now, but I figured I'd throw my hat in the ring in case anyone ever stumbles across this post. I spent the day frustratingly trying to create an example mdBook site using Github Pages, but kept banging my head against a wall.

Eventually, I figured it out and took the time to document the whole process and made a repository for it: https://github.com/tylerdotrar/Example-mdBook

Effectively, it's just a simple site with step-by-step directions on how to launch your first mdBook site via Github Pages.

TL;DR

• 1. Create a public repository.
• 2. Add a src directory.
• 3. Add your .md contents to that src directory (including a SUMMARY.md).
• 4. Create a simple book.toml.
• 5. Enable 'Read & Write Permissions' for Workflows in your repository.
• 6. Create a mdBook workflow (mdbook.yml)
• 7. Set your Github Page deployment to newly created 'gh-pages' branch.

[kg4zow]

@kg4zow : Thank you for the detailed explanation. Please see my response below.

Further, I actually used the instructions from the template-repo you referred in your original response to the OP. I used VS Code in Windows when following those instructions, but I was getting errors for many of those commands that I believe are Linux-specific ...

They are part of, or available for, just about every operating system in the world that isn't windows.

I've heard that there are ways to run Linux utilities under windows, but I don't have any details - the last time I used windows by choice was around the time "windows xp" came out, and the last time I used a microsoft IDE was around the same time - back then it was brand new, and it was just called "visual studio".

1. I think where I am failing could be because I am using Windows and the make command may not work there (not sure, I might be wrong). Any suggestion?

make is a standard utility for building software. If you have some kind of IDE installed, it might have the same thing, or it might have something similar - but yes, a big part of the problem is windows.

2. In case I am able to run all the commands as you described in your template-repo, I believe I need to go to the settings-->Code and automation-->pages-->Branch: gh-pages and save that setting. Is that right?

I know nothing about any specific settings for whatever software you're using. What I can tell you is this:

• Running mdbook build will create a book/ directory with the finished HTML, CSS, and javascript files.
• The contents of the book/ directory need to be copied to the repo root in the gh-pages branch.
• The gh-pages: rule in the Makefile does this, by ...
  • cloning a second "working directory" of the same repo, but in another directory on the computer
  • deleting everything in that other directory
  • copying the book/ directory to that other directory
  • in that other directory, commit changes
  • remove that other directory
  • push the changes up to github

I'll be honest, it sounds like you may want to find a way to run Linux - not individual Linux commands, but ... maybe install VirtualBox and run a Linux VM under that?

Update: didn't see your follow-on comment ... I'm guessing "WSL" is a way to run Linux commands under windows? In any event, I'm glad you got it working.

[kg4zow]

@tylerdotrar I looked at your example repo, very nice ... a few comments:

• Steps 2-4 are done automatically by running mdbook init.
• Steps 8-9 are only needed if you're doing the "custom hostname" functionality.

Part of my $DAYJOB involves writing documentation, and a few months ago I had to document how to do this for $DAYJOB. I found that readers were assuming that a custom hostname was required in order to set up the site, when it isn't. The pages ended up being a lot easier to understand when I separated "how to set up the empty repo" and "how to set up a custom hostname" from each other - in my case as separate sections on the same page, but separate pages under a common parent page would work as well - the idea is to have some kind of clear separation between the two. (I'm using the custom CSS from my personal template repo, so there's a big fat horizontal line across the page that separates things quite clearly.)

Also, thanks for sharing the workflow. I had thought about doing something similar, but the books I'm maintaining at work have to be published in two different places - one in github, and one to a web server on a private network that the github "runner" machines don't have access to, which is why I run make push to publish the books when I'm finished editing them.

[tylerdotrar]

@kg4zow I appreciate the response!

Yeah, I know that custom domains are not a hard requirement and that I was doing this completely manually, but it completely slipped my mind to notate that in the repo itself because some people might not realize that.

So because of that I have now added a disclaimer to the README adding your bullet of steps 2-4 being automatic, and that custom domains are NOT a hard requirement.