OurBigBook
  • 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>.
    Mammal.bigb
    = 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>.
    The following would fail and point you out the file and line of the failure:
    • nonexistent id:
      <Weird animal not documented>
    • duplicate IDs:
      = Animal
      
      == Dog
      
      == Cat
      
      == Dog
  • 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.bigb
        = Not readme
        
        == Not readme h2
        produces index.html and not-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:
        • index.html: which contains the full README.bigb output
        • split.html: split version of the above containing only the = My website header and not h2
        • h2.html: only contains the h2 header
        • not-readme.html contains the full output of not-readme.bigb
        • not-readme-split.html: only contains the = Not readme header
        • not-readme-h2.html: only contains the = Not readme h2 header
        Each of those pages automatically gets a table of contents
      • --embed-includes single file output from multiple input files. Includes are parsed smartly, not just source copy pasted, e.g. included headers are shifted from h1 to h2 correctly.
        On the previous sample filesystem, it would produce a single output file index.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"> and not-readme.bigb produces not-readme.html
        • when publishing, \x[not-readme] would render as <a href="not-readme"> and not-readme.bigb also produces not-readme.html, which the server converts to just http://my-website.com/not-readme
    • cross file configuration files to factor out common page parts like headers, footers and other metadata, e.g.:
    • table of contents that crosses input files via includes. E.g. in:
      README.bigb
      = My website
      
      == h2
      
      \Include[not-readme]
      not-readme.bigb
      = Not readme
      
      == Not readme h2
      the table of contents for index.html also contains the headers for not-readme.bigb producing:
      • My website
        • h2
          • Not readme
            • Not readme h2
      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.
    • check that local files and images linked to actually exist: \a external argument. E.g.:
      \a[i-don-exist.txt]
      would lead to a build error.
    • 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!
      would automatically add a preview of the image on the output.
  • 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]!
      would render:
      • \x[dog]{c}{p} as Dogs: capitalized because of {c} and pluralized because of {p}
      • \x[dog] as dogs: auto lowercased because its header = Dog does not have {c}
      • \x[snoopy] as Snoopy: 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].
      would render something like:
      <a href="#user-interface">User interface</a> is too long, I just say <a href="user-interface">UI</a>
      Furthermore, this also generates a output file:
      ui.html
      which redirects to the ain user-interface.html, so it serves as a way to have backward compatibility on page renames.
      And the title2 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}
      which renders something like:
      • \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 divs 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
  • automatic file upload and directory listing of non OurBigBook files: _raw directory, e.g.:
    • link to a file:
      The file \a[index.js] is cool.
      which renders as:
      The file index.js is cool.
    • link to a directory:
      The directory \a[file_demo] is cooler.
      which renders as:
      The directory file_demo is cooler.
  • 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 on ourbigbook.json:
      "media-providers": {
        "github": {
          "default-for": ["image", "video"],
          "path": "media",
          "remote": "yourname/myproject-media"
        }
      }
      you can use images in that repository with:
      \Image[My_image_basename.jpg]
      instead of:
      \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

Ancestors