This is likely the sanest approach possible, as it clearly specifies which media version matches which repository version through the submodule link.
Furthermore, it is possible to make the submodule clone completely optional by setting things up as follows. For your OurBigBook project yourname/myproject create a yourname/myproject-media with the media, and track it as a submodule under yourname/myproject/media.
Then, add to media-providers:
"media-providers": {
  "github": {
    "default-for": ["image", "video"],
    "path": "media",
    "remote": "yourname/myproject-media"
Now, as mentioned at media-providers, everything will work beautifully:
  • ourbigbook . local conversion will use images from media/ if it exists, e.g.:
    will render media/myimage.jpg. So after cloning the submodule, you will be able to see the images on the rendered pages without an internet connection.
    But if the submodule is not cloned, not problem, renders will detect that and automatically use GitHub images.
    Then, when you do:
    ourbigbook --publish
    the following happen:
    • \Image[myimage.jpg] uses the GitHub URL
    • automatically push media/ to GitHub in case there were any updates
    • also, that directory is automatically gitignore, so it won't be pushed as part of the main render and thus duplicate things


  1. Store images in a separate media repository
  2. Where to store images
  3. Image
  4. Macro
  5. OurBigBook Markup
  6. OurBigBook Project