- cross references to any header (including e.g. h2, h3, etc. in other files), images, etc. with amazing error checking and reporting: never break internal links without knoing again, and quickly find out what broke when you do. E.g.:animal.bigb
= Animal <Bats> are <flying animals>.
= Flying animal == Bat
Animal.bigb
would render something like:<a href="flying-animal.html#bat">Bats</a> are <a href="flying-animal.html">flying animals</a>.
- nonexistent id:
<Weird animal not documented>
- duplicate IDs:
= Animal == Dog == Cat == Dog
- nonexistent id:
- KaTeX server side mathematics, works on browsers with JavaScript disabled:
I like $\sqrt{2}$, but I adore this \x[equation-quadratic-equation]: $$ x^2 + 2x + 1 $$ {title=Quadratic equation}
- multi-file features out of the box so you don't need a separate wrapper like Jekyll to make a multi-page website:
- cross file references
- single-source multi-format output based on includes and build options:
- by default, one HTML per source with includes rendered as links between pages, e.g.:README.bigb
= My website == h2 \Include[not-readme]
= Not readme == Not readme h2
index.html
andnot-readme.html
- with the
-S
,--split-headers
option, you can output each header of an input file into a separate output file. The previous filesystem would produce:Each of those pages automatically gets a table of contentsindex.html
: which contains the fullREADME.bigb
outputsplit.html
: split version of the above containing only the= My website
header and noth2
h2.html
: only contains theh2
headernot-readme.html
contains the full output ofnot-readme.bigb
not-readme-split.html
: only contains the= Not readme
headernot-readme-h2.html
: only contains the= Not readme h2
header
--embed-includes
single file output from multiple input files. Includes are parsed smartly, not just source copy pasted, e.g. included headers are shifted fromh1
toh2
correctly.On the previous sample filesystem, it would produce a single output fileindex.html
which would contain a header structure like:= My website == h2 === Not readme ==== Not readme h2
- supports both local serverless rendering to HTML files for local viewing, and server oriented rendering such as GitHub pages, e.g. cross references automatically get
.html
extension and or not. E.g.:- locally, a link
\x[not-readme]
would render as<a href="not-readme.html">
andnot-readme.bigb
producesnot-readme.html
- when publishing,
\x[not-readme]
would render as<a href="not-readme">
andnot-readme.bigb
also producesnot-readme.html
, which the server converts to justhttp://my-website.com/not-readme
- locally, a link
- cross file configuration files to factor out common page parts like headers, footers and other metadata, e.g.:
main.liquid.html
: Liquid template used for all pages, see example at: Section "Play with the template"main.scss
: CSS stylesheet generated from SASS input, see example at: Section "Play with the template"ourbigbook.tex
: global LaTeX math definitions, e.g.:\newcommand{\abs}[1]{\left|#1\right|}
$\abs{x}$
ourbigbook.json
: per repository configuration options
- table of contents that crosses input files via includes. E.g. in:README.bigb
= My website == h2 \Include[not-readme]
= Not readme == Not readme h2
index.html
also contains the headers fornot-readme.bigb
producing:This means that you can split large splitDefault input files if rendering starts to slow you down, and things will still render exactly the same.- My website
- h2
- Not readme
- Not readme h2
- Not readme
- h2
- My website
- check that local files and images linked to actually exist:
\a
external
argument. E.g.:\a[i-don-exist.txt]
- associate headers to files with the
\H
file
argument e.g.:Here's an example of a nice image: \x[file/path/to/my/image.png]. = path/to/my/image.png {file} This image was taken when I was on vacation!
- advanced header/ID related features:
- ID-based header levels:
= Furry animal I like \x[furry-animal]{p}, especially my cat, here is his photo: \x[image-my-cat]. == Cat \Image[My_cat.jpg] {title=My cat}
- scopes either with directories or with within a single file:
See the important conclusion of my experiment: \x[report-of-my-experiment/conclusion] = Report of my experiment {scope} == Introduction == Middle == Conclusion
- cross reference title inflection for capitalization and pluralization, e.g.;
= Dog == Snoopy {c} \x[dog]{c}{p} are fun. But the \x[dog] I like the most is \x[snoopy]!
\x[dog]{c}{p}
asDogs
: capitalized because of{c}
and pluralized because of{p}
\x[dog]
asdogs
: auto lowercased because its header= Dog
does not have{c}
\x[snoopy]
asSnoopy
: title capitalization kept to upper case due to{c}
on the header== Snoopy
- synonyms, e.g.:
= User interface = UI {c} {synonym} {title2} \x[user-interface]{c} is too long, I just say \x[ui].
<a href="#user-interface">User interface</a> is too long, I just say <a href="user-interface">UI</a>
ui.html
user-interface.html
, so it serves as a way to have backward compatibility on page renames.And thetitle2
makes it appears on the main title under parenthesis, something like:<h1>User interface (UI)</h1>
- header disambiguation, e.g.:
My favorite fruits are \x[apple-fruit]{p}! My favorite least favorite brand is is \x[apple-company]! \x[apple] computers are too expensive. == Apple {disambiguate=fruit} == Apple {c} {disambiguate=company} = Apple {c} {synonym}
\x[apple-fruit]{p}
:<a href="apple-fruit">apples</a>
\x[apple-company]
:<a href="apple-company">Apple</a>
\x[apple]
: also<a href="apple-company">Apple</a>
because of the synonym== Apple\n{disambiguate=fruit}
:<h2 id="apple-fruit">Apple (fruit)</h2>
== Apple\n{disambiguate=company}
:<h2 id="apple-company">Apple (company)</h2>
- tags are regular headers:
\H
child
argument,\x
child
argument= Animal == Dog {tag=domestic} {tag=cute} == Cat {tag=domestic} {tag=cute} == Bat {tag=flying} = Flying = Cute = Domestic
- unlimited header levels, levels higher than 6 are rendered in HTML as an appropriately styled
div
s with an ID:= h1 == h2 === h3 ==== h4 ===== h5 ====== h6 ======= h7 ======== h8
- generate lists of incoming links between internal headers: it shows every internal link coming into the current page
- ID-based header levels:
- automatic file upload and directory listing of non OurBigBook files:
_raw
directory, e.g.: - is written in JavaScript and therefore runs natively on the browser to allow live previews as shown at: docs.ourbigbook.com/editor
- helps you with the publishing:
ourbigbook --publish
publishes in a single command to the configured target (default GitHub pages): Section "-p, --publish
"- OurBigBook tries to deal with media such as images and video intelligently for you, e.g.: Section "Where to store images". E.g. you can keep media in a separate media repository,
my-media-repository
, and then by configuring onourbigbook.json
:"media-providers": { "github": { "default-for": ["image", "video"], "path": "media", "remote": "yourname/myproject-media" } }
\Image[My_image_basename.jpg]
\Image[https://raw.githubusercontent.com/cirosantilli/myproject--media/master/My_image_basename.jpg]
inotifywait
watch and automatically rebuild with-w
,--watch
:ourbigbook --watch input-file.bigb
- automatic code formatting:
--format-source