OurBigBook logoOurBigBook Docs OurBigBook logoOurBigBook.comSite Source code

ourbigbook.json / media-providers

The media-providers entry of ourbigbook.json specifies properties of how media such as images and videos are retrieved and rendered.
The general format of media-providers looks like:
"media-providers": {
  "github": {
    "default-for": ["image"], // "all" to default for both image, video and anything else
    "path": "data/media/",    // data is gitignored, but should not be nuked like _out/
    "remote": "ourbigbook/ourbigbook-media"
  },
  "local": {
    "default-for": ["video"],
    "path": "media/",
  },
  "youtube": {}
}
Properties that are valid for every provider:
  • type: the provider implementation: local, github, wikimedia, youtube, or unknown. Provider names are arbitrary and are selected with {provider=NAME}. When type is omitted, it defaults to the provider's name, so existing configurations and markup continue to work unchanged. Custom names require an explicit type.
  • default-for: use this provider as the default for the given types of listed macros.
    The first character of the macros are case insensitive and must be given as lower case. Therefore e.g.:
    • image applies to both image and Image
    • giving Image is an error because that starts with an upper case character
  • title-from-src (bool): extract the title argument from the src by default for media such as images and videos as if the titleFromSrc macro argument had been given, see also: Section "Image ID"
For example, keep the implicit local provider for images next to your source files and add another local provider for a separate media repository:
"media-providers": {
  "media-repo": {
    "type": "local",
    "path": "../ourbigbook-media"
  }
}
Then \Image[logo.png] uses the source directory, while \Image[screenshot.png]{provider=media-repo} uses the media repository. You can also give a custom provider default-for and title-from-src settings, or explicitly override the type of a built-in name. Multiple local providers are walked for file previews and listings, uploaded by web, and merged into the published website. All share the site's root file namespace: their relative paths must not collide with each other or with source/generated files. Publishing uses each media repository's committed files, and uploaded article source is rewritten so the web server does not need your provider configuration.
Provider types and their type-specific properties:
  • local: tracked in the current Git repository as mentioned at Section "Store images inside the repository itself"
    • path: location of the cloned local repository relative to the root the main repository
      For example, set "local": {"path": "-/media"} to keep media in a separate repository or Git submodule under -/media. Relative image and video paths mirror the source file's directory inside the media directory: \Image[diagram.svg] in subdir/paper.bigb selects -/media/subdir/diagram.svg, and \Image[../shared.svg] selects -/media/shared.svg. A leading / explicitly selects the provider root: \Image[/diagram.svg] selects -/media/diagram.svg. For compatibility, an unprefixed path also falls back to the provider root if the source-relative file does not exist there. Without path, media paths remain relative to the source file.
      Normal source conversion skips -/ directories and the configured media directory, without needing an explicit ignoreConvert entry. Running ourbigbook . at the project root also walks the media directory, even when it is outside the project (for example ../wiki-media). Its files appear at the logical site root in -/dir listings, with automatic -/file previews unless an explicit file page already exists, and copies under -/raw. Media repository .bigb and .md files are treated as files to preview, not articles to convert. Git metadata and Git-ignored files are excluded. Local image and video renders still reference the media files directly.
      When publishing to GitHub, the media directory must be its own Git repository with a GitHub origin: OurBigBook pushes its current commit and merges its committed files into the generated site's root directory, preserving their relative paths. Images and videos use relative links on the site's own domain, without a Git commit SHA in their URLs. Git metadata is excluded, and collisions with generated files and symbolic links are rejected. Commit media changes before publishing; --dry-run and --dry-run-push suppress the push but still copy the media into the local publish output.
      With --web, files from the media directory are merged into your upload root, preserving their paths without an extra media/ prefix. Image and video references are rewritten automatically, preserving source-relative paths even when scoped headers become separate articles. Git-ignored files and Git metadata are excluded; unchanged files are skipped by hash. Collisions with source-repository files or directories abort before any files are uploaded or unlisted.
    • usedMediaOnly: default false. When true, only copy files from this provider that are referenced by the project's markup, both during ordinary local directory conversion and publishing. For example:
      "media-providers": {
  "media-repo": {
    "type": "local",
    "path": "../ourbigbook-media",
    "usedMediaOnly": true
  }
}
      This avoids duplicating unused media, such as large videos, in the output. Images, videos, ordinary file links and explicit file headers count as references, including those in included files and Markdown input. Unused provider files are omitted from new -/raw copies, automatic -/file previews, -/dir listings and the published root. Linking to a directory does not include all its files. Other providers and files in the main source repository are unaffected. Web uploads are unchanged. Per-target overrides under target are supported.
      As with ordinary local conversion, old generated files are not deleted. Use a clean output directory to remove copies left by earlier builds. Publishing rebuilds its output directory automatically.
      This setting cannot be combined with --publish-no-convert, because selection requires extracting the source references. Publishing still uses committed media snapshots and retains the normal media repository push behavior. Files referenced only by custom HTML, CSS or JavaScript are not detected; leave this setting off if those files are needed.
  • github: tracked in a separate Git repository as mentioned at Section "Store images in a separate media repository"
    • path: analogous to path for local: a local location for this GitHub provider, where the repository can optionally be cloned.
      When not during a run with the --publish option, OurBigBook checks if the path exists locally, and if it does, then it uses that local directory as the source intead of the GitHub repository.
      This allows you to develop locally without Internet and see the latest version of the images without pushing them.
      During publishing, the GitHub version is used instead.
      TODO make this even more awesome by finishing to implement github.com/ourbigbook/ourbigbook/issues/184:
      • automatically git push this repository during deployment to ensure that any asset changes will be available.
      • ignore the path from OurBigBook conversion as if added to ignore, and is not added to the final output, because you are already going to have a copy of it.
        This way you can use the sanes approach which is to track the directory as a Git submodule as mentioned at: store images in a separate media repository and track it as a git submodule, instead of either:
        • keeping it outside of the repository
        • keeping it in the repository but explicitly ignoring it as well, which is a bit redundant
    • remote: <github-username>/<repo-name>
  • youtube: YouTube videos
See also: github.com/ourbigbook/ourbigbook/issues/40

Ancestors (3)

  1. Ourbigbook.json
  2. OurBigBook CLI
  3. Home

Incoming links (8)