What's the best way to add version/commit signature to docs?

[behnam]

Some books on the Rust bookshelf show the rust version and exact commit from which the documents were built.

For example, see the bottom-right corner of these pages:

• https://doc.rust-lang.org/stable/book/
• https://doc.rust-lang.org/beta/book/
• https://doc.rust-lang.org/nightly/book/

What's the best way to do that in mdbook land? Is it possible at all to do so automatically?

If we need to build something for it, how about adding a version/commit signature to the bottom of the left-hand sidebar?

[budziq]

Hi @behnam

What's the best way to do that in mdbook land?

Currently one just builds mdbook against different versions and publishes the artifacts under different dirs/paths in the webserver. mdBook works here like any other static site generator.

Is it possible at all to do so automatically?

It sure is! Just have a travis build publish to different dirs/urls (ie. in single travis build you can generate several mdBooks sequentially put it different dirs).

If we need to build something for it, how about adding a version/commit signature to the bottom of the left-hand sidebar?

As described above, mdBook does not understand any versioning or identifiers and I'm not entirely convinced that it should. The only relatively clean solution that come to my mind is to have optional parameter for mdBook that could incorporate any string into some stylized caption at the bottom of the sidebar.

[Michael-F-Bryan]

You already have the ability to add custom CSS and JS which will be used by the generated book as well as the ability to tweak the template being used. It would probably be better to leverage a more general solution like that instead of adding corner cases to the HTML renderer.

We may need to make it easier to work with custom templates/css/js though. At the moment tweaking the generated output feels a lot harder than it should be...

[budziq]

adding corner cases to the HTML renderer.

I did not mean to add any corner cases to the HTML renderer itself. Possibly some way to give key value pairs at commandline to include in hbs if given key is present. With the custom js you'd have to generate the included js file from some template to pass the commit/version string from outside env.

[repi]

Did a quick and simple manual version of this in for our mdbooks in our CI where we on some of our pages have a footer-like section that looks like this:

---

{{#include ../../../generated-version.md}}

And then in CI simply before generating the docs we create that file with the info:

printf "Generated on %s with \`%s\`" $(date -u +"%Y-%m-%dT%H:%M:%SZ") $(git rev-parse HEAD) > generated-version.md

Which then looks like this:

Could be styled up further with CSS to have smaller text. Would be nice to have some proper footer file support in mdbook to include it there (or in sidebar)

[oberien]

I'm using the following hack to render the version at the beginning of every book page.

• in an empty folder, execute mdbook init --theme to get the current default theme template files
• copy over theme/index.hbs to your book as theme/index-template.hbs and add the version placeholder

  ...
  <div id="version" class="version">
    VERSION-PLACEHOLDER
  </div>
  <div id="content" class="content">
  ...
  

• add theme/index.hbs to your .gitignore
• copy over theme/css/print.css and add the following:

  #version {
    display: none;
  }
  

• add custom.css

  #version {
    font-size: .75em;
  }
  

• add the following to your book.toml

  [output.html]
  additional-css = ["custom.css"]
  
  [preprocessor.generate-version]
  renderers = ["html"]
  command = """sh -c 'jq ".[1]"; sed "s/VERSION-PLACEHOLDER/version: <code>$(git rev-parse HEAD)<\\/code> ($(git show -s --format="%ci" HEAD | cut -d" " -f1-2))/" theme/index-template.hbs > theme/index.hbs'"""
  

[jms1voalte]

I tried the idea above, i.e. creating an index-template.hbs with a dummy preprocessor script to generate an index.hbs, with the version info formatted the way I wanted it, at the bottom of the navigation bar (instead of being at the top or bottom of each individual page). It works, it looks nice, and I actually understand how the pieces all work.

I normally use mdbook serve --open to automatically render and reload the page in a local browser. The first time I did this after I got it all working, I noticed that after the first time it did an "automatic reload", it went into a loop and continuously rendered the book over and over again, because the theme/index.hbs file had been updated. One of the things being substituted into the generated index.hbs file is "date/time the HTML was generated", so of course it's going to be updated every time.

So my question is this: is there a way to tell mdbook serve to ignore certain files, or do I need to remove the "generated" timestamp from the template in order to prevent the looping?

Edit: the .gitignore file in the root of the "book" contains the following:

book
.DS_Store
._*
theme/index.hbs

[jms1voalte]

Changed the last line of the .gitignore file to ...

/theme/index.hbs

This seems to have stopped the "looping".

[kg4zow]

I've added this to a "template" repo that I use as a starting point when starting new documentation projects based on mdbook. The README.md file in this repo has what I hope is a more complete explanation of how this works.

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

[kg4zow]

Oh ... and in the interest of avoiding any confusion, "kg4zow" is my personal account, "jms1voalte" is my work account. Same guy, different desk.