OurBigBook Docs OurBigBook.comSite
An external link is a link that points to a resource that is not present in the curent OurBigBook project sources.
By default, most links are internal links, e.g. it is often the case in computer programming tutorials that we want to refer to source files in the current directory. So from our README.bigb, we could want to write something like:
Have a look at this amazing source file: \a[index.js].
which renders as:
Have a look at this amazing source file: index.js.
and here \a[ourbigbook] is a internal link.
A typicial external link is something like:
This is great website: https://cirosantilli.com
which renders as:
This is great website: cirosantilli.com
which points to an absolute URL.
OurBigBook considers a link relative by default if:
Therefore, the following links are external by default:
  • http://cirosantilli.com
  • https://cirosantilli.com
  • file:///etc/fstab
  • ftp://cirosantilli.com
and the following are internal by default:
  • index.js
  • ../index.js
  • path/to/index.js
  • /path/to/index.js. Note that paths starting with / refer to the root of the OurBigBook CLI deployment, not the root of the domain, see: link to the domain root path.
  • //example.com/path/to/index.js
A link being internal has the following effects
  • the correct relative path to the file is used when using nested scopes with -S, --split-headers. For example, if we have:
    = h1
    == h2
    === h3
    then in split header mode, h3 will be rendered to h2/h3.html.
    Therefore, if we didn't do anything about it, the link to index.js would render as href="index.js" and thus point to h2/index.js instead of the correct index.js.
    Instead, OurBigBook automatically converts it to the correct href="../index.js"
  • the _raw directory prefix is added to the link
  • existence of the file is checked on compilation. If it does not exist, an error is given.
Implemented at: github.com/ourbigbook/ourbigbook/issues/87 as relative, and subsequently modified to the more accurate/useful external.


  1. \a external argument
  2. Link
  3. Macro
  4. OurBigBook Markup
  5. OurBigBook Project