{"id":13736399,"url":"https://github.com/ourbigbook/ourbigbook","last_synced_at":"2025-04-11T12:32:31.417Z","repository":{"id":39000260,"uuid":"211290670","full_name":"ourbigbook/ourbigbook","owner":"ourbigbook","description":"The best way to publish your scientific knowledge. Source code for the entire OurBigBook Project: OurBigBook.com, ourbigbook CLI and the VS Code extension. A powerful static wiki generator and lightweight markup language to write complex structured wikis/books/blogs with multi-user mind-melding magic 🧙","archived":false,"fork":false,"pushed_at":"2025-03-25T08:33:04.000Z","size":11583,"stargazers_count":86,"open_issues_count":151,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T05:02:00.439Z","etag":null,"topics":["javascript","markup-language","nodejs","note-taking","static-site-generator","wiki"],"latest_commit_sha":null,"homepage":"https://OurBigBook.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ourbigbook.png","metadata":{"files":{"readme":"README.bigb","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["cirosantilli"]}},"created_at":"2019-09-27T10:03:46.000Z","updated_at":"2025-03-28T22:29:36.000Z","dependencies_parsed_at":"2023-02-18T04:35:17.117Z","dependency_job_id":"55b5fa09-1a36-4a3a-ac1e-ffeb1472fb64","html_url":"https://github.com/ourbigbook/ourbigbook","commit_stats":null,"previous_names":["cirosantilli/cirodown","cirosantilli/ourbigbook"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ourbigbook%2Fourbigbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ourbigbook%2Fourbigbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ourbigbook%2Fourbigbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ourbigbook%2Fourbigbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ourbigbook","download_url":"https://codeload.github.com/ourbigbook/ourbigbook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248402161,"owners_count":21097328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","markup-language","nodejs","note-taking","static-site-generator","wiki"],"created_at":"2024-08-03T03:01:21.100Z","updated_at":"2025-04-11T12:32:31.395Z","avatar_url":"https://github.com/ourbigbook.png","language":"JavaScript","funding_links":["https://github.com/sponsors/cirosantilli"],"categories":["JavaScript"],"sub_categories":[],"readme":"= OurBigBook Project\n{c}\n{id=ourbigbook}\n\n= OurBigBook Project\n{c}\n{synonym}\n\n\\b[https://OurBigBook.com[]]: The \\b[OurBigBook Project] is creating the ultimate tools to \u003cpublish\u003e \\b[textbooks]/\\b[\u003c#personal knowledge bases\u003e]/\\b[\u003c#Zettelkasten\u003e]/\\b[\u003c#digital gardens\u003e] in the \u003c#learn in public\u003e philosophy. It is our best shot yet at the final \\b[real-world \u003c#Encyclopedia Galactica\u003e] by allowing effective \\b[\u003c#mindmeld\u003e[mind melding]]/\\b[\u003c#collective intelligence\u003e] via the \\b[\u003ctopics feature\u003e].\n\n\\Image[logo.svg]\n{height=150}\n{title=\u003cproject logo\u003e[Logo of] the \u003cOurBigBook Project\u003e}\n\n\\b[Mission]: to live in a world where you can learn university-level #mathematics{p=1}, #physics{p=1}, \u003c#chemistry\u003e, #biology and #engineering from perfect free open source books that anyone can write to get famous.\n\n\\b[Ultimate goal]: destroy the currently grossly inefficient education system and replace it with a much more inspiring system where people learn what they want as fast as possible to reach their goals faster without so much useless pain.\n\n\\b[How to get there]: \u003cOurBigBook Web\u003e[create a website] (live at \\b[https://OurBigBook.com[]]) that incentivizes learners (notably university students taking courses) to write freely licensed university-level natural science books in their own words for free. Their motivation for doing that are:\n* getting their knowledge globally recognized and thus better jobs\n* improving the world\n* learning by teaching\n\n\\Video[https://www.youtube.com/watch?v=7JOJYx0mmhg]\n{title=Introduction to the \u003cOurBigBook Project\u003e}\n{height=500}\n\n\\b[Notable features]:\n\\Ol[\n* \\b[\u003ctopics\u003e]: groups the articles of different users about the same topic, sorted by upvote to achieve \u003c#mindmeld\u003e[mind melding]/\u003c#collective intelligence\u003e. This makes your articles easier for others to find.\n\n  \\Image[feature/topics/derivative.png]\n  {title=The \u003ctopics feature\u003e allows you to find the best version of a subject written by other users user}\n  {description=Live demo: \u003c#derivative\u003e.}\n  {provider=github}\n  {height=800}\n  {border}\n\n  \\Video[https://www.youtube.com/watch?v=54nxjC9BWTg]\n  {title=\u003cOurBigBook Web topics\u003e demo}\n  {disambiguate=intro}\n  {height=700}\n  {width=700}\n* \\b[local editing]: you can store all your \u003c#personal knowledge base\u003e content locally in a \u003cOurBigBook Markup\u003e[plaintext markup format] that can be edited locally and \u003cpublished\u003e with \u003cOurBigBook CLI\u003e to either:\n  * \\b[to \u003cOurBigBook.com\u003e]: to get awesome multi-user features like \u003cOurBigBook Web topics\u003e\n  * \\b[as HTML files to a \u003cstatic website\u003e]: you can host yourself for free on many external providers like \u003cGitHub Pages\u003e, and remain in full control\n  This way you can be sure that even if \u003courbigbook.com\u003e were to go down one day (which we have no plans to as it is quite cheap to host!), your content will still be perfectly readable as a static site.\n\n  \\Image[feature/local-editing/bigb-publish-to-web-or-static-editor-logos.svg]\n  {title=With OurBigBook you can \u003cpublish\u003e local \u003cOurBigBook markup\u003e[lightweight markup files] to either \u003cOurBigBook Web\u003e or as a \u003cstatic website\u003e}\n  {provider=github}\n  {height=600}\n  {disambiguate=intro}\n\n  \\Video[https://www.youtube.com/watch?v=Ghvlztiu6rI]\n  {title=Edit locally and \u003cpublish\u003e demo}\n  {disambiguate=intro}\n  {description=This shows editing \u003cOurBigBook Markup\u003e and \u003cpublishing\u003e it using the \u003cVS Code\u003e extension.}\n  {height=720}\n  {width=720}\n]\n\n\\b[Key links]:\n* https://OurBigBook.com[]: reference \u003cOurBigBook Web\u003e instance\n* donate to the OurBigBook Project: \u003cdonate\u003e\n* project announcements: \u003cnews\u003e{full}. Also posted in shorter form to \u003cofficial accounts\u003e{full} such as:\n  * https://twitter.com/OurBigBook[]\n  * https://mastodon.social/@OurBigBook\n* https://cirosantilli.com/ourbigbook-com[]: further rationale behind the project by the founder \u003cCiro Santilli\u003e \n* https://cirosantilli.com[]: showcase static demo document with interesting content, published with \u003cOurBigBook CLI\u003e. Primary inspiration for OurBigBook development.\n  * https://cirosantilli.com/oxford-nanopore-river-bacteria[]: a self-contained tutorial style part of the above. Note how internal links integrate seamlessly into the more global topic of biology, e.g. when talking about DNA we link to the global topic https://cirosantilli.com/dna[].\n  * https://github.com/cirosantilli/cirosantilli.github.io[] and https://github.com/cirosantilli/cirosantilli.github.io/blob/dev/oxford-nanopore-river-bacteria.bigb[]: source of the above showcase documents\n* \u003cdesign goals\u003e{full}: \u003cOurBigBook Markup\u003e and \u003cOurBigBook CLI\u003e feature overview\n* https://github.com/ourbigbook/ourbigbook[]: OurBigBook source code\n* https://github.com/ourbigbook/ourbigbook/issues[]: project issue tracker\n* https://github.com/ourbigbook/ourbigbook/blob/master/README.bigb[]: source for this document\n* https://docs.ourbigbook.com[]: rendered version of this document\n* https://docs.ourbigbook.com/_obb/dist/editor[]: live in-browser editor demo\n* https://github.com/ourbigbook/template[]: good template to get started with \u003cOurBigBook CLI\u003e, see \u003cOurBigBook CLI quick start\u003e{full}\n  * https://ourbigbook.github.io/template[]: the above \u003cpublished to GitHub Pages\u003e\n* https://cirosantilli.com/ourbigbook-media[]: media for the project such as for documentation and \u003cpublicity\u003e, more info: \u003cOurBigBook media repository\u003e{full}\n\n= Donate\n{parent=OurBigBook}\n\nTo donate:\n* https://cirosantilli.com/sponsor[]: give money directly to \u003cCiro Santilli\u003e \n* buy project merchandise, see: \u003cmerchandise\u003e{full}\n\nAll donated money currently just goes directly to \u003cCiro Santilli\u003e's personal bank account, the project founder and current lead. If things ever take off we will set up a legal entity to make things cleaner. One may dream. But for now, it would just add unnecessary overhead. Related: \u003cProject governance\u003e{full}.\n\nCiro announces funding milestones and transparently accounts for all donations at: https://cirosantilli.com/sponsor[]. When milestones are reached, he quits his day job and works full time on the project for a given ammount of time.\n\nWe are also happy to discuss paid contracts to implement specific features, to get in touch see: \u003ccontact\u003e.\n\n= Quick start\n{parent=OurBigBook}\n\nThe following sections cover different ways to use tools from the OurBigBook:\n* \u003cOurBigBook Web user manual\u003e: manual for \u003cOurBigBook Web\u003e, the dynamic website. With this approach, you can write content on the browser without downloading anything, and save it on our database.\n* convert local `.bigb` files with either:\n  * \u003cVisual Studio Code quick start\u003e\n  * \u003cOurBigBook CLI quick start\u003e\n  This method allows you to publish either as:\n  * a \u003cstatic website\u003e\n  * to \u003cOurBigBook Web\u003e\n* \u003cOurBigBook Markup quick start\u003e: covers specifically \u003cOurBigBook Markup\u003e, which is the markup language you use to write content in OurBigBook, both \u003cOurBigBook Web\u003e and \u003cOurBigBook CLI\u003e.\n\n  This is currently the only way to write OurBigBook content, but we would really like to add \u003ctodo/WYSIWYG\u003e[WYSIWYG] editor support one day!\n\n= OurBigBook Markup and CLI overview\n{parent=OurBigBook}\n\n= Features\n{parent=OurBigBook Markup and CLI overview}\n\n* \u003ccross references\u003e to any \u003cheader\u003e (including e.g. h2, h3, etc. \u003cinternal cross file references\u003e[in other files]), \u003cimages\u003e, etc. with amazing \u003cerror reporting\u003e[error checking and reporting]: never break internal links without knoing again, and quickly find out what broke when you do. E.g.:\n\n  animal.bigb\n  ``\n  = Animal\n\n  \u003cBats\u003e are \u003cflying animals\u003e.\n  ``\n  Mammal.bigb\n  ``\n  = Flying animal\n\n  == Bat\n  ``\n  `Animal.bigb` would render something like:\n  ``\n  \u003ca href=\"flying-animal.html#bat\"\u003eBats\u003c/a\u003e are \u003ca href=\"flying-animal.html\"\u003eflying animals\u003c/a\u003e.\n  ``\n  The following would fail and point you out the file and line of the failure:\n  * nonexistent id:\n    ``\n    \u003cWeird animal not documented\u003e\n    ``\n  * duplicate IDs:\n    ``\n    = Animal\n\n    == Dog\n\n    == Cat\n\n    == Dog\n    ``\n* https://katex.org/[KaTeX] server side \u003cmathematics\u003e, works on browsers with JavaScript disabled:\n  ``\n  I like $\\sqrt{2}$, but I adore this \\x[equation-quadratic-equation]:\n\n  $$\n  x^2 + 2x + 1\n  $$\n  {title=Quadratic equation}\n  ``\n* multi-file features out of the box so you don't need a separate wrapper like Jekyll to make a multi-page website:\n  * \u003ccross file references\u003e\n  * single-source multi-format output based on \u003cincludes\u003e and build options:\n    * by default, one HTML per source with includes rendered as links between pages, e.g.:\n\n      README.bigb\n      ``\n      = My website\n\n      == h2\n\n      \\Include[not-readme]\n      ``\n      not-readme.bigb\n      ``\n      = Not readme\n\n      == Not readme h2\n      ``\n      produces `index.html` and `not-readme.html`\n    * with the \u003csplit headers\u003e option, you can output each header of an input file into a separate output file. The previous filesystem would produce:\n      * `index.html`: which contains the full `README.bigb` output\n      * `split.html`: split version of the above containing only the `= My website` header and not `h2`\n      * `h2.html`: only contains the `h2` header\n      * `not-readme.html` contains the full output of `not-readme.bigb`\n      * `not-readme-split.html`: only contains the `= Not readme` header\n      * `not-readme-h2.html`: only contains the `= Not readme h2` header\n      Each of those pages automatically gets a \u003ctable of contents\u003e\n    * \u003c--embed-includes\u003e 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.\n\n      On the previous sample filesystem, it would produce a single output file `index.html` which would contain a header structure like:\n      ``\n      = My website\n\n      == h2\n\n      === Not readme\n\n      ==== Not readme h2\n      ``\n    * supports both local serverless rendering to HTML files for local viewing, and server oriented rendering such as GitHub pages, e.g. \u003ccross references\u003e automatically get `.html` extension and or not. E.g.:\n      * locally, a link `\\x[not-readme]` would render as `\u003ca href=\"not-readme.html\"\u003e` and `not-readme.bigb` produces `not-readme.html`\n      * when publishing, `\\x[not-readme]` would render as `\u003ca  href=\"not-readme\"\u003e` and `not-readme.bigb` also produces `not-readme.html`, which the server converts to just `http://my-website.com/not-readme`\n  * cross file configuration files to factor out common page parts like headers, footers and other metadata, e.g.:\n    * `ourbigbook.liquid.html`: https://github.com/Shopify/liquid[Liquid template] used for all pages, see example at: \u003cplay with the template\u003e{full}\n    * `main.scss`: CSS stylesheet generated from https://sass-lang.com/[SASS] input, see example at: \u003cplay with the template\u003e{full}\n    * `ourbigbook.tex`: global LaTeX math definitions, e.g.:\n      ``\n      \\newcommand{\\abs}[1]{\\left|#1\\right|}\n      ``\n      and then you can use:\n      ``\n      $\\abs{x}$\n      ``\n      in any .bigb file of the project.\n    * \u003courbigbook.json\u003e: per repository configuration options\n  * \u003ctable of contents\u003e that crosses input files via includes. E.g. in:\n\n    README.bigb\n    ``\n    = My website\n\n    == h2\n\n    \\Include[not-readme]\n    ``\n    not-readme.bigb\n    ``\n    = Not readme\n\n    == Not readme h2\n    ``\n    the table of contents for `index.html` also contains the headers for `not-readme.bigb` producing:\n    * My website\n      * h2\n        * Not readme\n          * Not readme h2\n    This means that you can split large \u003c\\H splitDefault argument\u003e[splitDefault] input files if rendering starts to slow you down, and things will still render exactly the same.\n  * check that local files and images linked to actually exist: \u003c\\a external argument\u003e. E.g.:\n    ``\n    \\a[i-don-exist.txt]\n    ``\n    would lead to a build error.\n  * associate headers to files or directories with the \u003c\\H file argument\u003e e.g.:\n    ``\n    Here's an example of a nice image: \\x[path/to/my/image.png]{file}.\n\n    = path/to/my/image.png\n    {file}\n\n    This image was taken when I was on vacation!\n    ``\n    would automatically add a preview of the image on the output. Display files and their metadata nicely directly on your static website rather than relying exclusively on GitHub as a file browser.\n* advanced header/ID related features:\n  * \u003cID-based header levels\u003e:\n    ``\n    = Furry animal\n\n    I like \\x[furry-animal]{p}, especially my cat, here is his photo: \\x[image-my-cat].\n\n    == Cat\n\n    \\Image[My_cat.jpg]\n    {title=My cat}\n    ``\n  * \u003cscopes\u003e either with directories or with within a single file:\n    ``\n    See the important conclusion of my experiment: \\x[report-of-my-experiment/conclusion]\n\n    = Report of my experiment\n    {scope}\n\n    == Introduction\n\n    == Middle\n\n    == Conclusion\n    ``\n  * \u003ccross reference title inflection\u003e for capitalization and pluralization, e.g.;\n    ``\n    = Dog\n\n    == Snoopy\n    {c}\n\n    \\x[dog]{c}{p} are fun. But the \\x[dog] I like the most is \\x[snoopy]!\n    ``\n    would render:\n    * `\\x[dog]{c}{p}` as `Dogs`: capitalized because of `{c}` and pluralized because of `{p}`\n    * `\\x[dog]` as `dogs`: auto lowercased because its header `= Dog` does not have `{c}`\n    * `\\x[snoopy]` as `Snoopy`: title capitalization kept to upper case due to `{c}` on the header `== Snoopy`\n  * \u003csynonyms\u003e, e.g.:\n    ``\n    = User interface\n\n    = UI\n    {c}\n    {synonym}\n    {title2}\n\n    \\x[user-interface]{c} is too long, I just say \\x[ui].\n    ``\n    would render something like:\n    ``\n    \u003ca href=\"#user-interface\"\u003eUser interface\u003c/a\u003e is too long, I just say \u003ca href=\"user-interface\"\u003eUI\u003c/a\u003e\n    ``\n    Furthermore, this also generates a output file:\n    ``\n    ui.html\n    ``\n    which redirects to the ain `user-interface.html`, so it serves as a way to have backward compatibility on page renames.\n\n    And the `title2` makes it appears on the main title under parenthesis, something like:\n    ``\n    \u003ch1\u003eUser interface (UI)\u003c/h1\u003e\n    ``\n  * \u003c\\H disambiguate argument\u003e[header disambiguation], e.g.:\n    ``\n    My favorite fruits are \\x[apple-fruit]{p}!\n\n    My favorite least favorite brand is is \\x[apple-company]! \\x[apple] computers are too expensive.\n\n    == Apple\n    {disambiguate=fruit}\n\n    == Apple\n    {c}\n    {disambiguate=company}\n\n    = Apple\n    {c}\n    {synonym}\n    ``\n    which renders something like:\n    * `\\x[apple-fruit]{p}`: `\u003ca href=\"apple-fruit\"\u003eapples\u003c/a\u003e`\n    * `\\x[apple-company]`: `\u003ca href=\"apple-company\"\u003eApple\u003c/a\u003e`\n    * `\\x[apple]`: also `\u003ca href=\"apple-company\"\u003eApple\u003c/a\u003e` because of the synonym\n    * `== Apple\\n{disambiguate=fruit}`: `\u003ch2 id=\"apple-fruit\"\u003eApple (fruit)\u003c/h2\u003e`\n    * `== Apple\\n{disambiguate=company}`: `\u003ch2 id=\"apple-company\"\u003eApple (company)\u003c/h2\u003e`\n  * tags are regular headers: \u003c\\H child argument\u003e, \u003c\\x child argument\u003e\n    ``\n    = Animal\n\n    == Dog\n    {tag=domestic}\n    {tag=cute}\n\n    == Cat\n    {tag=domestic}\n    {tag=cute}\n\n    == Bat\n    {tag=flying}\n\n    = Flying\n\n    = Cute\n\n    = Domestic\n    ``\n  * \u003cunlimited header levels\u003e, levels higher than 6 are rendered in HTML as an appropriately styled `div`s with an ID:\n    ``\n    = h1\n\n    == h2\n\n    === h3\n\n    ==== h4\n\n    ===== h5\n\n    ====== h6\n\n    ======= h7\n\n    ======== h8\n    ``\n  * generate lists of \u003cincoming links\u003e between internal headers: it shows every internal link coming into the current page\n* automatic file upload and directory listing of non OurBigBook files: \u003c`_raw` directory\u003e, e.g.:\n  * link to a file:\n    \\OurBigBookExample[[\n    The file \\a[index.js] is cool.\n    ]]\n  * link to a directory:\n    \\OurBigBookExample[[\n    The directory \\a[file_demo] is cooler.\n    ]]\n* is written in JavaScript and therefore runs natively on the browser to allow live previews as shown at: https://docs.ourbigbook.com/_obb/dist/editor[]\n* helps you with the publishing:\n  * \u003courbigbook --publish\u003e publishes in a single command to the configured target (default \u003cGitHub Pages\u003e)\n  * OurBigBook tries to deal with media such as images and video intelligently for you, e.g.: \u003cwhere to store images\u003e{full}. E.g. you can keep media in a separate media repository, `my-media-repository`, and then by configuring on \u003courbigbook.json\u003e:\n    ``\n    \"media-providers\": {\n      \"github\": {\n        \"default-for\": [\"image\", \"video\"],\n        \"path\": \"media\",\n        \"remote\": \"yourname/myproject-media\"\n      }\n    }\n    ``\n    you can use images in that repository with:\n    ``\n    \\Image[My_image_basename.jpg]\n    ``\n    instead of:\n    ``\n    \\Image[https://raw.githubusercontent.com/cirosantilli/myproject--media/master/My_image_basename.jpg]\n    ``\n  * `inotifywait` watch and automatically rebuild with \u003cwatch\u003e:\n    ``\n    ourbigbook --watch input-file.bigb\n    ``\n* automatic code formatting: \u003c--format-source\u003e\n\n= Design goals\n{parent=OurBigBook Markup and CLI overview}\n\nOurBigBook is designed entirely to allow writing complex professional HTML and PDF scientific books, blogs, articles and encyclopedias.\n\nOurBigBook aims to be the ultimate \u003clatex output format\u003e[LaTeX] \"killer\", allowing books to be finally published as either HTML or PDF painlessly (LaTeX being only a backend to PDF generation).\n\nIt aims to be \u003cfeatures\u003e[more powerful] and \u003csaner\u003e and than Markdown and Asciidoctor.\n\n= Saner\n{parent=Design goals}\n\nOriginally, OurBigBook was is meant to be both saner and more powerful than Markdown and Asciidoctor.\n\nBut alas, as Ciro started implementing and using it, he started to bring some Markdown \u003cinsane macro shortcut\u003e[insanity he missed back in].\n\nAnd so this \"degraded\" slightly into a language slightly saner than Asciidoctor but with an amazing Node.js implementation that makes it better for book writing and website publishing.\n\nNotably, we hope that our escaping will be a bit saner backslash escapes everything instead of Asciidoctor's \"different escapes for every case\" approach: https://github.com/asciidoctor/asciidoctor/issues/901\n\nBut hopefully, having starting from a saner point will still produce a saner end result, e.g. there are sane constructs for every insane one.\n\nIt is intended that this will be an acceptable downside as OurBigBook will be used primarily large complex content such as books rather than forum posts, and will therefore primarily written either:\n* in text editors locally, where users have more features than in random browser textareas\n* in a dedicated website that will revolutionize education, and therefore have a good JavaScript editing interface: https://github.com/cirosantilli/write-free-science-books-to-get-famous-website\n\nFor example, originally OurBigBook had exactly five magic characters, with similar functions as in LaTeX:\n* `\\` backslash to start a macro, like LaTeX\n* `{` and `}`: left and right square brackets to delimit \u003cpositional vs named arguments\u003e[optional macro arguments]\n* `[` and `]`: left and right curly braces bracket to start an optional arguments\nand double blank newlines for \u003cparagraphs\u003e if you are pedantic, but this later degenerated into many more with \u003cinsane macro shortcuts\u003e.\n\nWe would like to have only square brackets for both optional and mandatory to have even less magic characters, but that would make the language difficult to parse for computer and humans. LaTeX was right for once!\n\nThis produces a very regular syntax that is easy to learn, including doing:\n* arbitrary nesting of elements\n* adding arbitrary properties to elements\n\nThis sanity also makes the end tail learning curve of the endless edge cases found in Markdown and Asciidoctor disappear.\n\nThe language is designed to be philosophically isomorphic to HTML to:\n* further reduce the learning curve\n* ensure that most of HTML constructs can be reached, including arbitrary nesting\n\nMore precisely:\n* macro names map to tag names, e.g.: `\\\\a` to `\u003ca`\n* one of the arguments of macros, maps to the content of the HTML element, and the others map to attributes.\n\n  E.g., in a link:\n  ``\n  \\a[http://example.com][Link text\\]\n  ``\n  the first macro argument:\n  ``\n  http://example.com\n  ``\n  maps to the `href` of `\u003ca`, and the second macro argument:\n  ``\n  Link text\n  ``\n  maps to the internal content of `\u003ca\u003eLink text\u003c\u003e`.\n\n= More powerful\n{parent=Design goals}\n\nThe \u003csaner\u003e[high sanity of OurBigBook], also makes creating new macro extensions extremely easy and intuitive.\n\nAll built-in language features use the exact same API as new extensions, which ensures that the extension API is sane forever.\n\nMarkdown is clearly missing many key features such as block attributes and \u003ccross references\u003e, and has no standardized extension mechanism.\n\nThe \"more powerful than Asciidoctor\" part is only partially true, since Asciidoctor is very featureful can do basically anything through extensions.\n\nThe difference is mostly that OurBigBook is completely and entirely focused on making amazing scientific books, and so will have key features for that application out-of-the box, notably:\n* amazing header/ToC/ID features including proper error reports: never have a internal broken link or duplicate ID again\n* \u003cmathematics\u003e[server side pre-rendered maths with KaTeX]: all divs and spans are ready, browser only applies CSS, no JavaScript gets executed\n* \u003cpublish\u003e: we take care of website publishing for you out-of-the-box, no need to integrate into an external project like Jekyll\n* \u003csplit headers\u003e:\n  * https://github.com/asciidoctor/asciidoctor/issues/626 feature request\n  * https://github.com/owenh000/asciidoctor-multipage third party plugin that does it\nand we feel that some of those features have required specialized code that could not be easily implemented as a standalone macro.\n\nAnother advantage over Asciidoctor is that the reference implementation of OurBigBook is in JavaScript, and can therefore be used on browser live preview out of the box. Asciidoctor does Transpile to JS with https://github.com/opal/opal[Opal], but who wants to deal with that layer of complexity?\n\n= Related projects\n{parent=Design goals}\n\nStatic wiki generators: this is perhaps the best way of classifying this project :-)\n* https://github.com/gollum/gollum[]: already has a local server editor! But no WYSIWYG nor live preview. Git integration by default, so when you save on the UI already generates a Git commit. We could achieve that with: https://github.com/isomorphic-git/isomorphic-git[], would be really nice. Does not appear to have built-in static generation:\n  * https://stackoverflow.com/questions/7210391/have-anyone-use-gollum-site-to-generete-markdown-wikis-and-host-it-on-heroku\n  * https://github.com/dreverri/gollum-site\n  Does not appear to check that any links are correct.\n* https://github.com/wcchin/markypydia\n* https://obsidian.md/ closed source, Markdown with \u003ccross file reference\u003e + a SaaS. Appears to require payment for any publishing. 28k followers 2021: https://twitter.com/obsdmd[]. Founders are likely Canadians of Asian descent from Waterloo University: https://www.linkedin.com/in/lishid/ | https://www.linkedin.com/in/ericaxu/ also working in parallel on https://dynalist.io/ 2020 review at: https://www.youtube.com/watch?v=aK2fOQRNSxc Has offline editor with side-by-side preview. Compares with https://roamresearch.com/[Roam] and https://roamresearch.com/[Notion], but can't find any public publishing on those, seem to be enterprise only things.\n\nStatic book generators:\n* https://github.com/rstudio/bookdown[], https://bookdown.org/[]. Very similar feature set to what we want!!! Transpiles to markdown, and then goes through Pandoc: https://bookdown.org/yihui/bookdown/pandoc.html[], thus will never run on browser without huge translation layers. But does have an obscene amount of output formats however.\n* https://gohugo.io/[Hugo]. Pretty good, similar feature set to ours. But Go based, so hard on browser, and adds adhoc features on top of markdown once again\n* https://en.wikipedia.org/wiki/Personal_wiki\n  * https://github.com/vimwiki/vimwiki\n* https://github.com/hplgit/doconce\n* https://www.gwern.net/About#source is pretty interesting, uses https://github.com/jaspervdj/Hakyll/ + some custom stuff.\n* https://github.com/JerrySievert/bookmarkdown\n* https://www.gitbook.com/\n  * https://github.com/rust-lang/mdBook[]. Impressive integrated search feature. Like Gitbook but implemented in Rust.\n* https://github.com/facebook/docusaurus React + markdown based, written in TypeScript. So how can it be build fast? Gotta benchmark.\n* vimdoc: http://vimdoc.sourceforge.net/ They do have perfectly working \u003cInternal cross file references\u003e, see any page e.g. http://vimdoc.sourceforge.net/htmldoc/pattern.html[].\n* typst: https://github.com/typst/typst An attempt at a LaTeX killer. Has its own typesetting engine, does not simply transpile to LaTeX. Meant to be faster and simpler to write. No HTML output as of writing: https://github.com/typst/typst/issues/721\n\nLess related but of interest, similar philosophy to what Ciro wants, but no explicitly reusable system:\n* http://www.uprtcl.io/\n* https://libretexts.org\n* https://physics.info/\n* https://hypertextbook.com/\n* https://tutorial.math.lamar.edu/\n\n= Motivation\n{parent=Design goals}\n\n\u003cCiro Santilli\u003e developed OurBigBook to perfectly satisfy his writing style, which is basically \"create one humongous document where you document everything you know about a subject so everyone can understand it, and just keep adding to it\".\n\nhttps://cirosantilli.com[] is the first major document that he has created in OurBigBook.\n\nHe decided to finally create this new system after having repeatedly facing limitations of Asciidoctor which were ignored/wontfixed upstream, because Ciro's  writing style is not as common/targeted by Asciidoctor.\n\nFollowing large documents Ciro worked extensively on:\n* https://github.com/cirosantilli/china-dictatorship\n* https://github.com/cirosantilli/linux-kernel-module-cheat\nmade the limitations of Asciidoctor clear to Ciro, and were major motivation in this work.\n\nThe key limitations have repeatedly annoyed Ciro were:\n* cannot go over header level 6, addressed at: \u003cunlimited header levels\u003e\n* the need for \u003csplit headers\u003e to avoid one too large HTML output that will never get indexed properly by search engines, and takes a few seconds to load on any browser, which is unacceptable user experience\n\n= OurBigBook Markup\n{c}\n{parent=OurBigBook}\n\n= `.bigb` extension\n{synonym}\n{title2}\n\nOurBigBook Markup is the https://en.wikipedia.org/wiki/Lightweight_markup_language[lightweight markup language] used in the \u003cOurBigBook\u003e project.\n\nIt works both on the \u003cOurBigBook Web\u003e dynamic website, and on \u003cOurBigBook CLI\u003e static websites from the command line.\n\n\u003cOurBigBook Markup\u003e files use the `.bigb` extension.\n\n= OurBigBook Markup quick start\n{c}\n{parent=OurBigBook Markup}\n\n\u003cParagraphs\u003e are made by simplying adding an empty line, e.g.:\n\\OurBigBookExample[[\nMy first paragraph.\n\nAnd now my second paragraph.\n\nThird one to finish.\n]]\n\n\u003cHeaders\u003e are created by starting the line with equal signs. The more equal signs the deeper you are, e.g.:\n``\n= Animal\n\n== Mammal\n\n=== Dog\n\n=== Cat\n\n== Bird\n\n=== Pigeon\n\n=== Chicken\n``\nOn \u003cOurBigBook Web\u003e, the toplevel header of each page goes into a separate title box, so there things would just look like:\n* title box: \"Animal\"\n* body:\n  ``\n  == Mammal\n\n  === Dog\n\n  === Cat\n\n  == Bird\n\n  === Pigeon\n\n  === Chicken\n  ``\n\nYou can can use any header as a \u003c`\\H` `tag` argument\u003e[tag] of any other header, e.g.:\n``\n= Animal\n\n== Dog\n{tag=Cute animal}\n\n== Turtle\n{tag=Ugly animal}\n\n== Animal cuteness\n\n=== Cute animal\n\n=== Ugly animal\n``\n\nHeaders have several powerful features that you can read more about under \u003c`\\H` arguments\u003e, e.g. \u003c`\\H` `synonym` argument\u003e and \u003c`\\H` `disambiguate` argument\u003e.\n\nTo \u003cinternal cross references\u003e[link to any of your other pages], you can use angle brackets (less than/greater than) signs:\n``\nI have a \u003ccute animal\u003e. \u003cBirds\u003e are too noisy.\n``\nNote how \u003ccross reference title inflection\u003e[capitalization and pluralization generally just work].\n\nTo use a custom link text on a reference, use the following syntax:\n``\nI have a \u003ccute animal\u003e[furry animal]. \u003cBirds\u003e[feathery animals] are too noisy.\n``\n\nExternal links can be input directly as:\n\\OurBigBookExample[[\nThis is a great website: https://example.com\n\nI really like https://example.com[this website].\n]]\n\n\u003cCode blocks\u003e are done with backticks \\c[[`]]. With just one backtick, you get a code block inside the text:\n\\OurBigBookExample[[\nThe function call `f(x + 1, \"abc\")` is wrong.\n]]\nand with two ore more backticks you get a code block on its own line, and possibly with multiple code lines:\n\\OurBigBookExample[[\nThe function:\n``\nfunction f(x, s) {\n  return x + s\n}\n``\nis wrong.\n]]\n\n\u003cMathematics\u003e syntax is very similar to code blocks, you can just enter you LaTeX code in it:\n\\OurBigBookExample[[\nThe number $\\sqrt{2}$ is irrational.\n\nThe same goes for:\n$$\n\\frac{1}{\\sqrt{2}}\n$$\n]]\n\nWe also have \u003cBuilt-in math macros\u003e[a bunch of predefined macros from popular packages], e.g. `\\dv` from the https://mirrors.ibiblio.org/CTAN/macros/latex/contrib/physics/physics.pdf[`physics` package] for derivatives:\n\\OurBigBookExample[[\n$$\n\\dv{x^2}{x} = 2x\n$$\n]]\n\nYou can \u003cinternal cross references\u003e[refer] to specific equations like this:\n\\OurBigBookExample[[\nAs shown in \u003cequation Very important equation\u003e, this is true.\n\n$$\n\\frac{1}{\\sqrt{2}}\n$$\n{title=Very important equation}\n]]\n\n\u003cImages\u003e and \u003cvideos\u003e are also easy to add and \u003cinternal cross references\u003e[refer] to:\n\\OurBigBookExample[[\nAs shown at \u003cimage Cute chicken chick\u003e, chicks are cute.\n\n\\Image[https://upload.wikimedia.org/wikipedia/commons/thumb/c/c9/H%C3%BChnerk%C3%BCken_02.jpg/800px-H%C3%BChnerk%C3%BCken_02.jpg?20200716091201]\n{title=Cute chicken chick}\n\n\\Video[https://www.youtube.com/watch?v=j_fl4xoGTKU]\n{title=Top Down 2D Continuous Game by Ciro Santilli (2018)}\n]]\n\nImages can take a bunch of options, about which you can read more about at \u003cimage arguments\u003e. Most should be self explanatory, here is an image with a bunch of useful arguments:\n\\OurBigBookExample[[\n\\Image[https://upload.wikimedia.org/wikipedia/commons/thumb/c/c9/H%C3%BChnerk%C3%BCken_02.jpg/800px-H%C3%BChnerk%C3%BCken_02.jpg?20200716091201]\n{title=Ultra cute chicken chick}\n{description=\nThe chicken is yellow, and the hand is brown.\n\nThe background is green.\n}\n{border}\n{height=400}\n{source=https://commons.wikimedia.org/wiki/File:H%C3%BChnerk%C3%BCken_02.jpg}\n]]\n\n\u003cLists\u003e are written by starting the line with an asterisk `*`:\n\\OurBigBookExample[[\n* first item\n* second item\n* and the third\n]]\n\nA nested list:\n\\OurBigBookExample[[\n* first item\n  * first item version 1\n  * first item version 2\n    * first item version 2 1\n    * first item version 2 2\n* second item\n* and the third\n]]\n\nLists items can contain any markup, e.g. paragraphs. You just need to keep the same number of spaces, e.g.:\n\\OurBigBookExample[[\n* first item.\n\n  Second paragraph of first item.\n\n  And a third one.\n* second item\n  * second item v1\n\n    Another paragraph in second item v1\n  * second item v2\n]]\n\n\u003cTables\u003e are not very different from lists. We use double pipes for headers `||`, and a single pipe `|` for regular rows:\n\\OurBigBookExample[[\n|| City\n|| Sales\n\n| Salt Lake City\n| 124,00\n\n| New York\n| 1,000,000\n]]\n\nTo add a title we need to use an explicit `\\Table` macro as in:\n\\OurBigBookExample[[\nSee \u003ctable Sales per city\u003e for more information.\n\n\\Table\n{title=Sales per city}\n[\n|| City\n|| Sales\n\n| Salt Lake City\n| 124,00\n\n| New York\n| 1,000,000\n]\n]]\n\n= Macro\n{parent=OurBigBook Markup}\n\nThis section documents all OurBigBook macros.\n\nMacros are magic commands that do cool stuff, e.g. `\\Image` to create an image.\n\nThe most common macros also have \u003cinsane macro shortcuts\u003e to keep the syntax shorter.\n\nThe general macro syntax is described at \u003cOurBigBook Markup syntax\u003e{full}.\n\n= Link\n{parent=Macro}\n{tag=Macro with insane shortcut}\n\n= `\\a`\n{synonym}\n{title2}\n\n= `\\a` macro\n{synonym}\n\n\u003cInsane\u003e autolink, i.e. the link text is the same as the link address:\n\\OurBigBookExample[[\nThe website http://example.com is cool. See also:\n\n\\Q[http://example.com/2]\n]]\nExact parsing rules described at: \u003cinsane link parsing rules\u003e{full}.\n\nNote that the prefixes `http://` and `https://` are automatically removed from the displayed link, since they are so common that they woudly simply add noise.\n\nEquivalent sane version:\n\\OurBigBookExample[[[\nThe website \\a[http://example.com] is cool.\n\n\\Q[\\a[http://example.com/2]]\n]]]\n\nInsane link with custom text:\n\\OurBigBookExample[[The website http://example.com[example.com] is cool.]]\nEquivalent sane version:\n\\OurBigBookExample[[The website \\a[http://example.com][example.com] is cool.]]\nIf the custom text is empty, an autolink is generated. This is often useful if you want your link to be followed by punctuation:\n\\OurBigBookExample[[The website is really cool: http://example.com[].]]\nThis could also be achieved with the sane syntax of course, but this pattern saves a tiny bit of typing.\n\nLink with multiple paragraphs inside it:\n\\OurBigBookExample[[\n\\a[http://example.com][Multiple\n\nparagraphs]\n]]\n\nLink to a file in the current repository:\n\\OurBigBookExample[[\nThe file \\a[index.js] is cool.\n]]\nThis links to a raw view of that file.\n\nLink to a directory in the current repository:\n\\OurBigBookExample[[\nThe directory \\a[file_demo] is cooler.\n]]\nThis links to an output file that contains a generated directory listing of that directory.\n\n= `\\a` `href` argument\n{parent=Link}\n\nThe link target, e.g. in:\n``\n\\a[http://example.com]\n``\n`href` equals `http://example.com`.\n\nImportant behaviours associated with this property for local links are detailed at \u003c\\a external argument\u003e{full}:\n* they are checked for existence in the local filesystem\n* they are modified to account for \u003cscopes\u003e with \u003csplit headers\u003e\n\n= `\\a` `ref` argument\n{parent=Link}\n{tag=Boolean argument}\n\nAnalogous to the \u003c\\x ref argument\u003e, e.g.:\n\\OurBigBookExample[[Trump said this and that.https://en.wikipedia.org/wiki/Donald_Trump_Access_Hollywood_tape#Trump's_responses{ref}https://web.archive.org/web/20161007210105/https://www.donaldjtrump.com/press-releases/statement-from-donald-j.-trump{ref} Then he said that and this.https://en.wikipedia.org/wiki/Donald_Trump_Access_Hollywood_tape#Trump's_responses{ref}https://web.archive.org/web/20161007210105/https://www.donaldjtrump.com/press-releases/statement-from-donald-j.-trump{ref}]]\n\n= `\\a` `external` argument\n{parent=Link}\n{tag=Boolean argument}\n\nIf given and true, forces a the link to be an \u003cexternal link\u003e.\n\nOtherwise, the external is automatically guessed based on the address given as explained at \u003cexternal link\u003e{full}.\n\nCommon use cases for the `external` argument is to link to non OurBigBook content in the curent domain, e.g.:\n* \u003clink to the domain root path\u003e for \u003cSubdirectory deployments\u003e\n* link non OurBigBook subdirectories. E.g., https://github.com/cirosantilli/cirosantilli.github.io/blob/master/README.bigb was rendered at https://cirosantilli.com[], and contains links `\\a[markdown-style-guide]{external}` to https://cirosantilli.com/markdown-style-guide[], whose source lives in a separate non-OurBigBook repository: https://github.com/cirosantilli/markdown-style-guide/\n\n= Internal links are smart\n{parent=`\\a` `external` argument}\n\n= Link to the domain root path\n{synonym}\n{title2}\n\nThe \u003c`\\a` `external` argument\u003e can be used to refer to the root of the domain. E.g. suppose that we have a \u003csubdirectory deployment\u003e under `https://mydomain.com/subdir/`. Then:\n* `\\a[/somepath]` refers to the directory `/subdir/somepath`\n* `\\a[/somepath]{external}` refers t othe directory `/somepath`\n\n= Subdirectory deployment\n{parent=a `external` argument}\n\nTODO test if it works. But we want it to be possible to deploy \u003cOurBigBook CLI\u003e static websites on subdirectories, e.g.:\n``\nhttps://mydomain.com/subdir/\nhttps://mydomain.com/subdir/mathematics\n``\nIf it doesn't work, it should be easy to make it work, as we use relative links almost everywhere already. Likely there would only be some minor fixes to the \u003c--template\u003e arguments.\n\n= External link\n{parent=a `external` argument}\n\n= Internal link\n{synonym}\n\nAn external link is a link that points to a resource that is not present in the curent OurBigBook project sources.\n\nBy 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:\n\\OurBigBookExample[[Have a look at this amazing source file: \\a[index.js].]]\nand here `\\a[ourbigbook]` is a internal link.\n\nA typicial external link is something like:\n\\OurBigBookExample[[This is great website: https://cirosantilli.com]]\nwhich points to an absolute URL.\n\nOurBigBook considers a link relative by default if:\n* it is not a \u003cURL with protocol\u003e\n\nTherefore, the following links are external by default:\n* `http://cirosantilli.com`\n* `https://cirosantilli.com`\n* `file:///etc/fstab`\n* `ftp://cirosantilli.com`\nand the following are internal by default:\n* `index.js`\n* `../index.js`\n* `path/to/index.js`\n* `/path/to/index.js`. Note that paths starting with `/` refer to the root of the \u003cOurBigBook CLI\u003e deployment, not the root of the domain, see: \u003clink to the domain root path\u003e.\n* `//example.com/path/to/index.js`\n\nA link being internal has the following effects\n* the correct relative path to the file is used when using nested \u003cscopes\u003e with \u003csplit headers\u003e. For example, if we have:\n  ``\n  = h1\n\n  == h2\n  {scope}\n\n  === h3\n\n  \\a[index.js]\n  ``\n  then in split header mode, `h3` will be rendered to `h2/h3.html`.\n\n  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`.\n\n  Instead, OurBigBook automatically converts it to the correct `href=\"../index.js\"`\n* the \u003c`_raw` directory\u003e prefix is added to the link\n* existence of the file is checked on compilation. If it does not exist, an error is given.\n\nImplemented at: https://github.com/ourbigbook/ourbigbook/issues/87[] as `relative`, and subsequently modified to the more accurate/useful `external`.\n\n= `_dir` directory\n{parent=a `external` argument}\n\nThe `_dir` directory tree contains file listings of files in the `_raw` directory.\n\nWe originally wanted to place these listings under `_raw` itself, but this leads to unsolvable conflicts when there are files called `index.html` present vs the index.\n\n= `_file` output directory\n{parent=a `external` argument}\n\n= `_file` directory\n{synonym}\n\nAnalogous to the \u003c`_raw` directory\u003e, but for the \u003c`\\H` `file` argument\u003e.\n\n= `_raw` directory\n{parent=a `external` argument}\n\n\u003cOurBigBook\u003e places output files that are not the output of `.bigb` to `.html` conversion (i.e. `.html` output files) under the `_raw/` prefix of the output.\n\n\u003cInternal links\u003e then automatically add the `_raw/` prefix to every link.\n\nFor example, consider an input directory that contains:\n\nnotindex.bigb\n``\n= Hello\n\nCheck out \\a[myfile.c].\n\nThe source code for this file is at: \\a[notindex.bigb].\n\n\\Image[myimg.png]\n``\n\nmyfile.c\n``\nint i = 1;\n``\n\nmyimg.png\n``\nBinary!\n``\n\nAfter conversion with:\n``\nourbigbook .\n``\nthe following files would exist in the output directory:\n* `notindex.html`: converted output of `notindex.bigb`\n* `_raw/notindex.bigb`: a copy of the input source code `notindex.bigb`\n* `_raw/myfile.c`: a copy of the input file `myfile.c`\n* `_raw/myimg.png`: a copy of the input file `myimg.c`\nand all links/image references would work and automtically point to the correct locations under `_raw`.\n\nSome live examples:\n* link to a file:\n\n  \\OurBigBookExample[[\n  The file \\a[index.js] is cool.\n  ]]\n* link to a directory:\n  \\OurBigBookExample[[\n  The directory \\a[file_demo] is cooler.\n  ]]\n\nThe reason why a `_raw` prefix is needed it to avoid naming conflicts with OurBigBook outputs, e.g. suppose we had the files:\n* `configure`\n* `configure.bigb`\nThen, in a server that omits the `.html` extension, if we didn't have `_raw/` both `configure.html` and `configure` would be present under `/configure`. With `_raw` we instead get:\n* `_raw/configure`: the input `/configure` file\n* `configure`: the HTML\n\n= URL with protocol\n{c}\n{parent=a `external` argument}\n\nA URL with protocol is a URL that matches the regular expression `^[a-zA-Z]+://`. The following are examples of URLs with protocol:\n* `http://cirosantilli.com`\n* `https://cirosantilli.com`\n* `file:///etc/fstab`\n* `ftp://cirosantilli.com`\n\nThe following aren't:\n* `index.js`\n* `../index.js`\n* `path/to/index.js`\n* `/path/to/index.js`\n* `//example.com/path/to/index.js`. This one is a bit tricky. Web browsers would consider this as a https://stackoverflow.com/questions/28446314/why-use-protocol-relative-urls-at-all[protocol-relative URL], which technically implies a protocol, although that protocol would be different depending how you are viewing the file, e.g. locally through `file://` vs on a with website `https://`.\n\n  For simplicity's sake, we just consider it as a URL without protocol.\n\n= Insane link parsing rules\n{parent=Link}\n\nInsane start at any of the recognized protocols are the ones shown at: \u003cknown URL protocols\u003e{full}.\n* `http://`\n* `https://`\nabsolutely anywhere if not escaped, e.g.:\n``\nahttp://example.com\n``\nrenders something like:\n``\na \u003ca href=\"http://example.com\"\u003e\n``\nTo prevent expansion, you have to escape the protocol with a backslash `\\\\`, e.g.:\n``\n\\http://example.com\n``\nEmpty domains like:\n``\nhttp://\n``\ndon't becomes links however. But this one does:\n``\nhttp://a\n``\n\nInsane links end when any \u003cinsane link termination character\u003e is found.\n\nAs a consequence, to have an insane link followed immediately by a punctuation like a period you should use an empty argument as in:\n\\OurBigBookExample[[Check out this website: http://example.com[].]]\notherwise the punctuation will go in it. Another common use case is:\n\\OurBigBookExample[[As mentioned on the tutorial (http://example.com[see this link]).]]\n\nIf you want your link to include one of the terminating characters, e.g. `]`, all characters can be escaped with a backslash, e.g.:\n\\OurBigBookExample[[Hello http://example.com/\\]a\\}b\\\\c\\ d world.]]\n\nNote that the `http://example.com` inside `\\a[http://example.com]` only works because we do some post-processing magic that prevents its expansion, otherwise the link would expand twice:\n\\OurBigBookExample[[\n\\P[http://example.com]\n\n\\a[http://example.com]\n]]\nThis magic can be observed with \u003c--help-macros\u003e by seeing that the `href` argument of the `a` macro has the property:\n``\n\"elide_link_only\": true,\n``\n\n= Insane link termination character\n{parent=Insane link parsing rules}\n\nThe following characters are the \"insane link termination characters\":\n* space ` `\n* newline `\\n`\n* open or close square bracket `[` or `]`\n* open or close curly braces `{` or `}`\n\u003cInsane cross references\u003e and \u003cinsane topic links with a single word\u003e terminate if any of these characters are found, see also: \u003cinsane link parsing rules\u003e{full}.\n\n= Bold\n{parent=Macro}\n{title2=`\\b`}\n\n\\OurBigBookExample[[Some \\b[bold] text.]]\n\n= Line break\n{parent=Macro}\n{title2=`\\br`}\n\nThere is basically one application for this: poetry, which would be too ugly with \u003ccode block\u003e due to fixed width font:\n\\OurBigBookExample[[\nParagraph 1 Line 1\\br\nParagraph 1 Line 2\\br\n\nParagraph 2 Line 1\\br\nParagraph 2 Line 2\\br\n]]\n\n= Code block\n{parent=Macro}\n{tag=Macro with insane shortcut}\n{title2=\\c[[``]], \\c[[`]], `\\C`, `\\c`}\n\nInline code (code that should appear in the middle of a paragraph rather than on its own line) is done with a single backtick (\\c[[`]]) \u003cinsane macro shortcut\u003e:\n\\OurBigBookExample[[My inline `x = 'hello\\n'` is awesome.]]\nand block code (code that should appear on their own line) is done with two or more backticks (\\c[[``]]):\n\\OurBigBookExample[[\n``\nf() {\n  return 'hello\\n';\n}\n``\n]]\n\nThe sane version of inline code is a lower case `c`:\n\\OurBigBookExample[[[My inline \\c[[x = 'hello\\n']] is awesome.]]]\nand the sane version of block math is with an upper case `C`:\n\\OurBigBookExample[[[\n\\C[[\nf() {\n  return 'hello\\n';\n}\n]]\n]]]\n\nThe capital vs lower case theme is also used in other elements, see: \u003cblock vs inline macros\u003e.\n\nIf the content of the sane code block has many characters that you would need to \u003cescape characters\u003e[escape], you will often want to use \u003cliteral arguments\u003e, which work just like the do for any other argument. For example:\n\\OurBigBookExample[[[[\n\\C[[[\nA paragraph.\n\n\\C[[\nAnd now, some long, long code, with lots\nof chars that you would need to escape:\n\\ [  ] {  }\n]]\n\nA paragraph.\n]]]\n]]]]\nNote that the initial newline is skipped automatically in code blocks, just as for any other element, due to: \u003cargument leading newline removal\u003e, so you don't have to worry about it.\n\nThe distinction between inline `\\c` and block `\\C` code blocks is needed because in HTML, https://stackoverflow.com/questions/5371787/can-i-have-a-pre-tag-inside-a-p-tag-in-tumblr/58603596#58603596[`pre` cannot go inside `P`].\n\nWe could have chosen to do some magic to differentiate between them, e.g. checking if the block is the only element in a paragraph, but we decided not to do that to keep the language saner.\n\nAnd now a code block outside of \u003c\\OurBigBookExample\u003e to test how it looks directly under \u003ctoplevel\u003e:\n\n``\nHello\n\nHello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello\n    HelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHello\nHello\n``\n\nNow with short description with math and underline:\n\n``\nHello\n\nHello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello\n    HelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHelloHello\nHello\n``\n{description=My long code! $a_b$}\n\nAnd now a very long inline code: `Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello Hello`\n\n\\Comment[[[[\nTODO implement.\nWe can have cross references to code blocks as for other elements such as \\x[image]{p}:\n\\OurBigBookExample[[[\nSee this awesome code \\x[my-code]:\n``\nab\ncd\n``\n{id=my-code}\n]]]\n]]]]\n\n= `\\C` argument\n{parent=Code block}\n\n= `\\C` `description` argument\n{parent=`\\C` argument}\n{tag=`description` argument}\n\nSee: \u003c`description` argument\u003e{full}.\n\nExample:\n\n\\OurBigBookExample[[\nSee the: \u003ccode Python hello world\u003e.\n\n``\nprint(\"Hello wrold\")\n``\n{title=Python hello world}\n{description=Note thow this is super short unlike the C hello world!}\n]]\n\n= `\\C` `title` argument\n{parent=`\\C` argument}\n{tag=`title` argument}\n\nSee: \u003c`title` argument\u003e{full}.\n\nExample:\n\n\\OurBigBookExample[[\nSee the: \u003ccode C hello world\u003e.\n\n``\n#include \u003cstdio.h\u003e\n\nint main(void) {\n    puts(\"hello, world\");\n}\n``\n{title=C hello world}\n]]\n\n= Comment\n{parent=Macro}\n{title2=`\\Comment`}\n\nThe `Comment` and `comment` macros are regular macros that does not produce any output. Capitalization is explained at: \u003cblock vs inline macros\u003e{full}.\n\nYou will therefore mostly want to use it with a \u003cliteral arguments\u003e[literal argument], which will, as for any other macro, ignore any macros inside of it.\n\\OurBigBookExample[[[\nBefore comment.\n\n\\Comment[[\nInside comment.\n]]\n\nAfter comment.\n]]]\n\nAnd an inline one:\n\\OurBigBookExample[[[\nMy inline \\comment[[inside comment]] is awesome.\n\n\\comment[[inside comment]] inline at the start.\n]]]\n\n= Header\n{parent=Macro}\n{title2=`\\H`}\n\n\u003cInsane\u003e with `= ` (equal sign space):\n``\n= My h1\n\n== My h2\n\n=== My h3\n``\nInsane headers end at the first newline found. They cannot therefore contain raw newline tokens.\n\nEquivalent sane:\n``\n\\H[1][My h1]\n\n\\H[2][My h2]\n\n\\H[3][My h3]\n``\n\nCustom ID for \u003ccross references\u003e on insane headers:\n``\n= My h1\n{id=h1}\n\n== My h2\n{id=h2}\n\n=== My h3\n{id=h3}\n``\n\nSane equivalent:\n``\n\\H[1][My h1]{id=h1}\n\n\\H[2][My h2]{id=h2}\n\n\\H[3][My h3]{id=h3}\n``\n\n= Unlimited header levels\n{parent=Header}\n\nThere is no limit to how many levels we can have, for either sane or insane headers!\n\nHTML is randomly limited to `h6`, so OurBigBook just renders higher levels as an `h6` with a `data-level` attribute to indicate the actual level for possible CSS styling:\n``\n\u003ch6 data-level=\"7\"\u003eMy title\u003c/h6\u003e\n``\n\nThe recommended style is to use insane headers up to `h6`, and then move to sane one for higher levels though, otherwise it becomes very hard to count the `=` signs.\n\nTo avoid this, we considered making the insane syntax be instead:\n``\n= 1 My h1\n= 2 My h2\n= 3 My h3\n``\nbut it just didn't feel as good, and is a bit harder to type than just smashing `=` n times for lower levels, which is the most common use case. So we just copied markdown.\n\n= My h3\n{parent=Unlimited header levels}\n\n= My h4\n{parent=My h3}\n\n= My h5\n{parent=My h4}\n\n= My h6\n{parent=My h5}\n\n= My h7\n{parent=My h6}\n\n= My h8\n{parent=My h7}\n\n= My h9\n{parent=My h8}\n\n= My h10\n{parent=My h9}\n\n= My h11\n{parent=My h10}\n\n= My h12\n{parent=My h11}\n\n= My h13\n{parent=My h12}\n\n= Skipping header levels\n{parent=Header}\n\nThe very first header of a document can be of any level, although we highly recommend your document to start with a `\\H[1]`, and to contain exactly just one `\\H[1]`, as this has implications such as:\n* `\\H[1]` is used for the document title: \u003cHTML document title\u003e\n* `\\H[1]` does not show on the \u003ctable of contents\u003e\n\nAfter the initial header however, you must not skip a header level, e.g. the following would give an error because it skips level 3:\n``\n= my 1\n\n== my 1\n\n==== my 4\n``\n\n= The toplevel header\n{parent=Header}\n\n= Toplevel header\n{synonym}\n\nThe toplevel header of a OurBigBook file is its first header and the one with the lowest level, e.g. in a document with recommended syntax:\n``\n= Animal\n\n== Dog\n\n=== Bull Terrier\n\n== Cat\n``\nthe header `= Animal` is the tolevel header.\n\nBeing the toplevel header gives a header some special handling described in child sections of the section and elsewhere throughout this documentation.\n\nThe toplevel header is only defined if the document has only a single header of the highest level. e.g. like the following has only a single `h2`:\n``\n== My 2\n\n=== My 3 1\n\n=== My 3 2\n``\n\n= The toplevel header IDs don't show\n{parent=The toplevel header}\n\nHeader IDs won't show for the toplevel level. For example, the headers would render like:\n``\nMy 2\n\n1. My 3 1\n\n2. My 3 2\n``\nrather than:\n``\n1. My 2\n\n1.2. My 3 1\n\n1.2. My 3 2\n``\nThis is because in this case, we guess that the `h2` is the toplevel.\n\n= The ID of the first header is derived from the filename\n{parent=The toplevel header}\n\nTODO: we kind of wanted this to be the ID of the toplevel header instead of the first header, but this would require an extra postprocessing pass (to determine if the first header is toplevel or not), which might affect performance, so we are not doing it right now.\n\nWhen the OurBigBook input comes from a file (and not e.g. \u003cstdin\u003e), the default ID of the first header in the document is derived from the basename of the OurBigBook input source file rather than from its title.\n\nThis is specially relevant when \u003cinclude\u003e[including] other files.\n\nFor example, in file named `my-file.bigb` which contains:\n``\n= Awesome ourbigbook file\n``\nthe ID of the header is `my-file` rather than `awesome-ourbigbook-file`. See also: \u003cautomatic ID from title\u003e.\n\nIf the file is an \u003cindex file\u003e other than \u003cthe toplevel index file\u003e, then the basename of the parent directory is used instead, e.g. the toplevel ID of a file:\n``\nmy-subdir/README.bigb\n``\nwould be:\n``\n#my-subdir\n``\nrather than:\n``\n#README.bigb\n``\n\nFor the toplevel index file however, the ID is just taken from the header itself as usual. This is done because you often can't general control the directory name of a project.\n\nFor example, a \u003cpublish to GitHub Pages\u003e[GitHub pages] root directory must be named as `\u003cusername\u003e.github.io`. And users may need to rename directories to avoid naming conflicts.\n\nAs a consequence of this, the toplevel index file cannot \u003cinclude\u003e[be included in other files].\n\n= `\\H` arguments\n{parent=Header}\n\n= `\\H` `c` argument\n{parent=H arguments}\n\nIf given, makes the header capitalized by default on \u003ccross file references\u003e.\n\nMore details at: \u003ccross reference title inflection\u003e{full}.\n\n= `\\H` `child` argument\n{parent=H arguments}\n{tag=`multiple` argument}\n{tag=Disabled macro argument}\n\nThis \u003cmultiple argument\u003e marks given IDs as being children of the current page.\n\nThe effect is the same as adding the \u003c\\x child argument\u003e argument to an under the header. Notably, such marked target IDs will show up on the \u003ctagged\u003e autogenerated \u003cheader metadata section\u003e.\n\nThis argument is deprecated in favor of the \u003cH tag argument\u003e.\n\nExample:\n``\n= Animal\n\n== Mammal\n\n=== Bat\n\n=== Cat\n\n== Wasp\n\n== Flying animal\n{child=bat}\n{child=wasp}\n\n\\x[bat]\n\n\\x[wasp]\n``\nrenders exactly as:\n``\n= Animal\n\n== Mammal\n\n=== Bat\n\n=== Cat\n\n== Wasp\n\n== Flying animal\n\n\\x[bat]{child}\n\n\\x[wasp]{child}\n``\n\nThe header `child` syntax is generally preferred because at some point while editing the content of the header, you might accidentally remove mentions to e.g. `\\x[bat]{child}`, and then the relationship would be lost.\n\nThe \u003c\\H tag argument\u003e does the same as the \u003c\\x child argument\u003e but in the opposite direction.\n\n= `\\H` `file` argument\n{parent=H arguments}\n\nIf given, the current section contains metadata about file or other resource with the given URL.\n\nIf empty, the URL of the file is extracted directly from the header. Otherwise, the given URL is used.\n\nfor example:\n``\n= path/to/myfile.c\n{file}\n\nAn explanation of what this file is about.\n``\nrenders a bit like:\n```\n= path/to/myfile.c\n{id=_file/path/to/myfile.c}\n\nAn explanation of what this file is about.\n\n\\a[path/to/myfile.c]\n\n``\n// Contents of path/to/myfile.c\nint main() {\n  return 1;\n}\n``\n```\nso note how:\n* \u003cautomatic ID from title\u003e does not normalize the path, e.g. it does not convert `/` to `-`.\n\n  Also, a \u003c_file output directory\u003e[`_file/` prefix] is automatically added to the ID. This is needed with \u003csplit headers\u003e to avoid a collision between:\n  * `path/to/myfile.c`: the actual file\n  * `_file/path/to/myfile.c`: the metadata about that file. Note that locally the `.html` extension is added as in `file/path/to/myfile.c.html` which avoids the collision. But on a server deployment, the `.html` is not present, and there would be a conflict if we didn't add that `file/` prefix.\n* a link to the is added automatically, since users won't be able to click it from the header, as clicking on the header will just link to the header itself\n* a preview is added. The type of preview is chosen as follows:\n  * if the URL has an image extension, do an \u003cimage\u003e preview\n  * otherwise if the URL has a video extension, or is a YouTube URL, do a \u003cvideo\u003e preview\n  * otherwise, don't show a preview, as we don't know anything sensible to show\n\nIn some cases however, especially when dealing with external URLs, we might want to have a more human readable title with a non empty `file` argument:\n``\nThe video \\x[tank-man-by-cnn-1989] is very useful.\n\n= Tank Man by CNN (1989)\n{c}\n{file=https://www.youtube.com/watch?v=YeFzeNAHEhU}\n\nAn explanation of what this video is about.\n``\nwhich renders something like:\n``\nThe video \\x[tank-man-by-cnn-1989] is very useful.\n\n= Tank Man by CNN (1989)\n{id=_file/https://www.youtube.com/watch?v=YeFzeNAHEhU}\n\n\\Video[https://www.youtube.com/watch?v=YeFzeNAHEhU]\n\nAn explanation of what this video is about.\n``\n\nTo make \u003cinternal cross references\u003e to `{file}` headers, use the \u003c`\\x` `file` argument\u003e.\n\n= `\\H` `file` argument toplevel header\n{parent=H file argument}\n\nTo create a separate file with the \u003c`\\H` `file` argument\u003e set on the \u003ctoplevel header\u003e, you must put it under the special \u003c`_file` input directory\u003e. For example:\n``\n_file/path/to/myfile.txt.bigb\n``\ncould contain something like:\n``\n= myfile.txt\n{file}\n\nDescription of my amazing file.\n``\nand it would be associated to the file:\n``\npath/to/myfile.txt\n``\n\nThe content of the header `= myfile.txt` is arbitrary, as it can be fully inferenced from the file path `_file/path/to/myfile.txt.bigb`. TODO add linting for it. Perhaps we should make adding a header be optional and auto-generate that header instead. But having at least an optional header is good as a way of being able to set header properties like \u003ctags\u003e.\n\n= `_file` input directory\n{parent=H file argument}\n\nSee: \u003c`\\H` `file` argument toplevel header\u003e{full}.\n\n= `\\H` `file` argument demo\n{parent=H file argument}\n\nThis section contains some live demoes of the \u003c`\\H` `file` argument\u003e.\n\n= file_demo\n{file}\n{parent=H file argument demo}\n\nAn explanation of what this directory is about.\n\n= file_demo/file_demo_subdir\n{file}\n{parent=H file argument demo}\n\nGoing deeper.\n\n= file_demo/hello_world.js\n{file}\n{parent=H file argument demo}\n\nAn explanation of what this text file is about.\n\nAnother line.\n\n= file_demo/file_demo_subdir/hello_world.js\n{file}\n{parent=H file argument demo}\n\nGoing deeper.\n\n= index.js\n{file}\n{parent=H file argument demo}\n{tag=Overview of files in this repository}\n\nThis is a central source file that basically contains all the functionality of the \u003cOurBigBook Library\u003e, so basically the \u003cOurBigBook markup\u003e-to-\u003cOutput format\u003e[whatever] (e.g. \u003chtml output format\u003e[HTML]) conversion code, including parsing and rendering.\n\nThings that are not there are things that only use markup conversion, e.g.:\n* \u003cOurBigBook CLI\u003e: does conversion from command line\n* \u003cOurBigBook Web\u003e\n\nThis file must be able to run in the browser, so it must not contain any Node.js specifics.\n\nIt exposes the central `convert` function for markup conversion.\n\nYou should normally use the packaged `_obb/ourbigbook.js` version of this file when using ourbigbook as an external dependency.\n\nThis file is large, and large text files are not previewed, as they would take up too much useless vertical space and disk memory/bandwidth.\n\n= file_demo/my.bin\n{file}\n{parent=H file argument demo}\n\nBinary files are not rendered.\n\n= Tank_man_standing_in_front_of_some_tanks.jpg\n{file}\n{parent=H file argument demo}\n\nAn explanation of what this image is about.\n\nAnother line.\n\n= Tank Man by CNN (1989)\n{c}\n{file=https://www.youtube.com/watch?v=YeFzeNAHEhU}\n{parent=H file argument demo}\n\nAn explanation of what this video is about.\n\n= `\\H` `numbered` argument\n{c}\n{parent=H arguments}\n{tag=Boolean argument}\n\nThis \u003cboolean argument\u003e determines whether renderings of a header will have section numbers or not. This affects all of:\n* \u003cheaders\u003e themselves\n* \u003ctable of contents\u003e links\n* \u003ccross references\u003e with the \u003c\\x full argument\u003e\nThis option can be set by default for all files with:\n\nBy default, headers are numbered as in a book, e.g.:\n``\n= h1\n\n== h2\n\n=== h3\n\n==== h4\n``\nrenders something like:\n``\n= h1\n\nTable of contents\n* 1. h2\n  * 1.1. h3\n    * 1.1.1. h4\n\n== 1. h2\n\n=== 1.1. h3\n\n==== 1.1.1. h4\n``\n\nHowever, for documents with a very large number of sections, or \u003cunlimited header levels\u003e[deeply nested headers] those numbers start to be more noise than anything else, especially in the table of contents and you are better off just referring to IDs. E.g. imagine:\n``\n1.3.1.4.5.1345.3.2.1. Some deep level\n``\n\nWhen documents reach this type of scope, you can disable numbering with the `numbered` option.\n\nThis option can be set on any header, and it is inherited by all descendants.\n\nThe option only affects descendants.\n\nE.g., if in the above example turn numbering off at `h2`:\n``\n= h1\n\n== h2\n{numbered=0}\n\n=== h3\n\n==== h4\n``\nthen it renders something like:\n``\n= h1\n\nTable of contents\n* 1. h2\n  * h3\n    * h4\n\n== 1. h2\n\n=== h3\n\n==== h4\n``\n\nThe more common usage pattern to disable it on toplevel and enable it only for specific \"tutorial-like sections\". An example can be seen at:\n* https://cirosantilli.com/[]: huge toplevel wiki, for which we don't want numbers\n* https://cirosantilli.com/x86-paging[]: a specific tutorial, for which we want numbers\nwhich is something like:\n``\n= Huge toplevel wiki\n{numbered=0}\n\n== h2\n\n=== A specific tutorial\n{numbered}\n{scope}\n\n==== h4\n\n===== h5\n``\nthen it renders something like:\n``\n= Huge toplevel wiki\n\nTable of contents\n* h2\n  * A specific tutorial\n    * 1. h4\n      * 1.1.  h5\n\n== h2\n\n=== A specific tutorial\n\n==== 1. h4\n\n===== 1.1. h5\n``\nNote how in this case the number for `h4` is just `1.` rather than `1.1.1.`. We only show numberings relative to the first non-numbered header, because the `1.1.` wouldn't be very meaningful otherwise.\n\n= `\\H` `parent` argument\n{c}\n{parent=H arguments}\n\n= ID-based header levels\n{c}\n{synonym}\n{title2}\n\nIn addition to the basic way of specifying header levels with an explicit level number as mentioned at \u003cheader\u003e{full}, OurBigBook also supports a more indirect ID-based mechanism with the `parent` argument of the `\\H` element.\n\nWe hightly recommend using `parent` for all but the most trivial documents.\n\nFor example, the following fixed level syntax:\n``\n= My h1\n\n== My h2 1\n\n== My h2 2\n\n=== My h3 2 1\n``\nis equivalent to the following ID-based version:\n``\n= My h1\n\n= My h2 1\n{parent=my-h1}\n\n= My h2 2\n{parent=my-h1}\n\n= My h3 2 1\n{parent=my-h2-h}\n``\n\nThe main advantages of this syntax are felt when you have a huge document with \u003cunlimited header levels\u003e[very large header depths]. In that case:\n* it becomes easy to get levels wrong with so many large level numbers to deal with. It is much harder to get an ID wrong.\n* when you want to move headers around to improve organization, things are quite painful without a refactoring tool (which we intend to provide in the \u003cbrowser editor with preview\u003e), as you need to fix up the levels of every single header.\n\n  If you are using the ID-based syntax however, you only have to move the chunk of headers, and change the `parent` argument of a single top-level header being moved.\n\nNote that when the `parent=` argument is given, the header level must be `1`, otherwise OurBigBook assumes that something is weird and gives an error. E.g. the following gives an error:\n``\n= My h1\n\n== My h2\n{parent=my-h1}\n``\nbecause the second header has level `2` instead of the required `= My h2`.\n\nWhen \u003cscopes\u003e are involved, the rules are the same as those of internal reference resolution, including the leading `/` to break out of the scope in case of conflicts.\n\nLike the \u003c\\H child argument\u003e, `parent` also performs \u003cID target from title\u003e on the argument, allowing you to use the original spaces and capitalization in the target as in:\n``\n= Flying animal\n\n= Bat\n{parent=Flying animal}\n``\nwhich is equivalent to:\n``\n= Flying animal\n\n= Bat\n{parent=flying-animal}\n``\n\nSee also: \u003cheader explicit levels vs nesting design choice\u003e{full} for further rationale.\n\n= ID-based header levels and scope resolution\n{c}\n{parent=H parent argument}\n\nWhen mixing both \u003c\\H parent argument\u003e and \u003cscopes\u003e, things get a bit complicated, because when writing or parsing, we have to first determine the parent header before resolving scopes.\n\nAs a result, the follow simple rules are used:\n* start from the last header of the highest level\n* check if the `{parent=XXX}` is a suffix of its ID\n* if not, proceed to the next smaller level, and so on, until a suffix is found\n\nFollowing those rules for example, a file `tmp.bigb`:\n``\n= h1\n{scope}\n\n= h1 1\n{parent=h1}\n{scope}\n\n= h1 1 1\n{parent=h1-1}\n\n= h1 1 2\n{parent=h1-1}\n\n= h1 1 3\n{parent=h1/h1-1}\n\n= h1 2\n{parent=h1}\n{scope}\n\n= h1 2 1\n{parent=h1-2}\n{scope}\n\n= h1 2 1 1\n{parent=h1-2/h1-2-1}\n``\nwill lead to the following header tree with \u003c--log headers\u003e:\n``\n= h1  tmp\n== h2 1 tmp/h1-1\n=== h3 1.1 tmp/h1-1/h1-1-1\n=== h3 1.2 tmp/h1-1/h1-1-2\n=== h3 1.3 tmp/h1-1/h1-1-3\n== h2 2 tmp/h1-2\n=== h3 2.1 tmp/h1-2/h1-2-1\n==== h4 2.1.1 tmp/h1-2/h1-2-1/h1-2-1-1\n``\n\n= Header explicit levels vs nesting design choice\n{parent=H parent argument}\n\nArguably, the language would be even saner if we did:\n``\n\\H[My h1][\n\nParagraph.\n\n\\H[My h2][]\n]\n``\nrather than having explicit levels as in `\\H[1][My h1]` and so on.\n\nBut we chose not to do it like most markups available because it leads to too many nesting levels, and hard to determine where you are without tooling.\n\nCiro later \"invented\" (?) \u003c\\H parent argument\u003e, which he feels reaches the perfect balance between the advantages of those two options.\n\n= `\\H` `scope` argument\n{parent=H arguments}\n\n= Scope\n{synonym}\n\nIn some use cases, the sections under a section describe inseparable parts of something.\n\nFor example, when documenting an experiment you executed, you will generally want an \"Introduction\", then a \"Materials\" section, and then a \"Results\" section for every experiment.\n\nOn their own, those sections don't make much sense: they are always referred to in the context of the given experiment.\n\nThe problem is then how to get unique IDs for those sections.\n\nOne solution, would be to manually add the experiment ID as prefix to every subsection, as in:\n``\n= Experiments\n\nSee: \\x[full-and-unique-experiment-name/materials]\n\n== Introduction\n\n== Full and unique experiment name\n\n=== Introduction\n{id=full-and-unique-experiment-name/introduction}\n\nSee our awesome results: \\x[full-and-unique-experiment-name/results]\n\nFor a more general introduction to all experiments, see: \\x[introduction].\n\n=== Materials\n{id=full-and-unique-experiment-name/materials}\n\n=== Results\n{id=full-and-unique-experiment-name/results}\n``\n\nbut this would be very tedious.\n\nTo keep those IDs shorter, OurBigBook provides the `scope` \u003cboolean argument\u003e property of \u003cheaders\u003e, which works analogously to C++ namespaces with the header IDs.\n\nUsing `scope`, the previous example could be written more succinctly as:\n``\n= Experiments\n\nSee: \\x[full-and-unique-experiment-name/materials]\n\n== Introduction\n\n== Full and unique experiment name\n{scope}\n\n=== Introduction\n\nSee our awesome results: \\x[results]\n\nFor a more general introduction to all experiments, see: \\x[/introduction].\n\n=== Materials\n\n=== Results\n``\n\nNote how:\n* full IDs are automatically prefixed by the parent scopes prefixed and joined with a slash `/`\n* we can refer to other IDs withing the current scope without duplicating the scope. E.g. `\\x[results]` in the example already refers to the ID `full-and-unique-experiment-name/materials`\n* to refer to an ID outside of the scope and avoid name conflicts with IDs inside of the current scope, we start a reference with a slash `/`\n\n  So in the example above, `\\x[/introduction]` refers to the ID `introduction`, and not `full-and-unique-experiment-name/introduction`.\n\n= `scope` resolution\n{parent=H scope argument}\n\nWhen nested scopes are involved, \u003ccross references\u003e resolution peels off the scopes one by one trying to find the closes match, e.g. the following works as expected:\n``\n= h1\n{scope}\n\n== h2\n{scope}\n\n=== h3\n{scope}\n\n\\x[h2]\n``\nHere OurBigBook:\n* first tries to loop for an `h1/h2/h3/h2`, since `h1/h2/h3` is the current scope, but that ID does not exist\n* so it removes the `h3` from the current scope, and looks for `h1/h2/h2`, which is still not found\n* then it removes the `h2`, leading to `h1/h2`, and that one is found, and therefore is taken\n\n= Directory-based `scope`\n{parent=H scope argument}\n\nPutting files in subdirectories of the build has the same effect as adding a \u003cscope\u003e to their top level header.\n\nNotably, all headers inside that directory get the directory prepended to their IDs.\n\nThe toplevel directory is determined as described at: \u003cthe toplevel index file\u003e.\n\n= Test scope 1\n{parent=H scope argument}\n{scope}\n\nFor fun and profit.\n\n= Test scope 2\n{parent=Test scope 1}\n{scope}\n\nLet's break this local link: \\a[ourbigbook].\n\n= Not scoped\n{parent=Test scope 2}\n\n= `\\H` `scope` argument of toplevel headers\n{parent=H scope argument}\n\nWhen \u003cthe toplevel header\u003e is given the `scope` property OurBigBook automatically uses the file path for the scope and heaves fragments untouched.\n\nFor example, suppose that file `full-and-unique-experiment-name` contains:\n``\n= Full and unique experiment name\n{scope}\n\n== Introduction\n\n== Materials\n``\n\nIn this case, multi-file output will generate a file called `full-and-unique-experiment-name.html`, and the URL of the subsections will be just:\n* `full-and-unique-experiment-name.html#introduction`\n* `full-and-unique-experiment-name.html#materials`\ninstead of\n* `full-and-unique-experiment-name.html#full-and-unique-experiment-name/introduction`\n* `full-and-unique-experiment-name.html#full-and-unique-experiment-name/materials`\n\nSome quick interactive cross file link tests:\n* \u003cnot readme with scope\u003e\n* \u003cnot readme with scope/h2\u003e\n* \u003cnot readme with scope/image My image\u003e\n\n= `\\H` `splitDefault` argument\n{parent=H arguments}\n{tag=Boolean argument}\n\nWhen using \u003csplit headers\u003e, \u003ccross references\u003e always point to non-split pages as mentioned at \u003ccross reference targets in split headers\u003e.\n\nIf the `splitDefault` \u003cboolean argument\u003e is given however:\n* the split header becomes the default, e.g. `index.html` is now the split one, and `nosplit.html` is the non-split one\n* the header it is given for, and all of its descendant headers will use the split header as the default internal cross target, unless the header is already rendered in the current page. This does not propagate across \u003cincludes\u003e however.\n\nFor example, consider `README.bigb`:\n``\n= Toplevel\n{splitDefault}\n\n\\x[h2][toplevel to h2]\n\n\\x[notreadme][toplevel to notreadme]\n\n\\Include[notreadme]\n\n== h2\n``\nand `notreadme.bigb`:\n``\n= Notreadme\n\n\\x[h2][notreadme to h2]\n\n\\x[notreadme][notreadme to notreadme h2]\n\n== Notreadme h2\n``\nThen the following links would be generated:\n* `index.html`: split version of `README.bigb`, i.e. does not contain `h2`\n  * `toplevel to h2`: `h2.html`. Links to the split version of `h2`, since `h2` is also affected by the `splitDefault` of its parent, and therefore links to it use the split version by default\n  * `toplevel to notreadme`: `notreadme.html`. Links to non-split version of `notreadme.html` since that header is not `splitDefault`, because `splitDefault` does not propagate across includes\n* `nosplit.html` non-split version of `README.bigb`, i.e. contains `h2`\n  * `toplevel to h2`: `#h2`, because even though `h2` is `splitDefault`, that header is already present in the current page, so it would be pointless to reload the split one\n  * `toplevel to notreadme`: `notreadme.html`\n* `h2.html` split version of `h2` from `README.bigb`\n* `notreadme.html`: non-split version of `notreadme.bigb`\n  * `notreadme to h2`: `h2.html`, because `h2` is `splitDefault`\n  * `notreadme to notreadme h2`: `#notreadme-h2`\n* `notreadme-split.html`: split version of `notreadme.bigb`\n  * `notreadme to h2`: `h2.html`, because `h2` is `splitDefault`\n  * `notreadme to notreadme h2`: `notreadme.html#notreadme-h2`, because `notreadme-h2` is not `splitDefault`\n\nThe major application of this if you like work with a huge `README.bigb` containing thousands of random small topics.\n\nSplitting those into separate source files would be quite laborious, as it would require duplicating IDs on the filename, and setting up \u003cincludes\u003e.\n\nHowever, after this README reaches a certain size, page loads start becoming annoyingly slow, even despite already loading large assets like \u003cimages\u003e video \u003cvideos\u003e only on hover or click: the annoying slowness comes from the loading of the HTML itself before the browser can jump to the ID.\n\nAnd even worse: this README corresponds to the main index page of the website, which will make what a large number of users will see be that slowness.\n\nTherefore, once this README reaches a certain size, you can add the `splitDefault` attribute to it, to make things smoother for readers.\n\nAnd if you have a smaller, more self-contained, and highly valuable tutorial such as https://cirosantilli.com/x86-paging[], you can just split that into a separate `.bigb` source file.\n\nThis way, any links into the smaller tutorial will show the entire page as generally desired.\n\nAnd any links from the tutorial, back to the main massive README will link back to split versions, leading to fast loads.\n\nThis feature was implemented at: https://github.com/ourbigbook/ourbigbook/issues/131\n\nNote that this huge README style is not recommended however. \u003cCiro Santilli\u003e used to do it, but moved away from it. The currently recommended approach is to manually create not too large subtrees in each page. This way, readers can easily view several nearby sections without having to load a new page every time.\n\n= `\\H` `splitSuffix` argument\n{parent=H arguments}\n\nIf given, add a custom suffix to the output filename of the header when using \u003csplit headers\u003e.\n\nIf the given suffix is empty, it defaults to `-split`.\n\nFor example, given:\n``\n= my h1\n\n== my h2\n``\na `--split-headers` conversion would normally place `my h2` into a file called:\n``\nmy-h2.html\n``\nHowever, if we instead wrote:\n``\n== my h2\n{splitSuffix}\n``\nit would not be placed under:\n``\nmy-h2-split.html\n``\nand if we set a custom one as:\n``\n== my h2\n{splitSuffix=asdf}\n``\nit would go instead to:\n``\nmy-h2-asdf.html\n``\n\nThis option is useful if the root of your website is written in OurBigBook, and you want to both:\n* have a section that talks about some other project\n* host the documentation of that project inside the project source tree\n\nFor example, https://cirosantilli.com with source at https://github.com/cirosantilli/cirosantilli.github.io has a quick section about OurBigBook: https://cirosantilli.com#ourbigbook[].\n\nTherefore, without a custom suffix, the split header version of that header would go to https://docs.ourbigbook.com[], which would collide with this documentation, that is present in a separate repository: https://github.com/ourbigbook/ourbigbook[].\n\nTherefore a `splitSuffix` property is used, making the split header version fall under `/ourbigbook-split`, and leaving the nicer `/ourbigbook` for the more important project toplevel.\n\nIf given on the \u003cthe toplevel headers\u003e, which normally gets a suffix by default to differentiate from the non-split version, it replaces the default `-split` suffix with a custom one.\n\nFor example if you had `notindex.bigb` as:\n``\n= Not index\n``\nthen it would render to:\n``\nnotindex-split.bigb\n``\nbut if you used instead:\n``\n= Not index\n{splitSuffix=asdf}\n``\nthen it would instead be:\n``\nnotindex-asdf.bigb\n``\n\n= `\\H` `synonym` argument\n{parent=H arguments}\n\n= Synonym\n{synonym}\n\nThis option is similar to \u003c\\H title2 argument\u003e but it additionally:\n* creates a new ID that you can refer to, and renders it with the alternate chosen title\n* the rendered ID on \u003ccross references\u003e is the same as what it is a synonym for\n* the synonym header is not rendered at all, including in the \u003ctable of contents\u003e\n* when using \u003csplit headers\u003e, a redirect output file is generated from the synonym to the main ID\n\nExample:\n``\n= Parent\n\n== GNU Debugger\n{c}\n\n= GDB\n{c}\n{synonym}\n\nI like to say \\x[gdb] because it is shorter than \\x[gnu-debugger].\n``\nrenders something like:\n``\n= GNU Debugger\n\nI like to say \\a[#gnu-debugger][GDB] because it is shorter than \\x[#gnu-debugger][GNU Debugger].\n``\nFurthermore, if \u003csplit headers\u003e is used, another file is generated:\n``\ngdb.html\n``\nwhich contains a redirection from `gdb.html` to `gnu-debugger.html`.\n\nImplemented at: https://github.com/ourbigbook/ourbigbook/issues/114\n\n= `\\H` `title` argument\n{parent=H synonym argument}\n{tag=`title` argument}\n\nContains the main content of the header. The \u003cinsane syntax\u003e:\n``\n= My title\n``\nis equivalent to the sane:\n``\n\\H[1][My title]\n``\nand in both cases `My title` is the title argument.\n\nThe \u003c`title` argument\u003e is also notably used for \u003cautomatic ID from title\u003e.\n\n= Automatic ID from title\n{parent=H title argument}\n\nIf a \u003cthe toplevel header\u003e[non-toplevel] macro has the `title` argument is present but no explicit `id` argument is given, an \u003celement ID\u003e is created automatically from the `title`, by applying the following transformations:\n* do a \u003cid output format\u003e conversion on the title to remove for example any HTML tags that would be present in the conversion output\n* convert all characters to lowercase. This uses \u003cJavaScript case conversion\u003e. Note that this does convert non-ASCII characters to lowercase, e.g. `É` to `é`.\n* if \u003courbigbook.json/id normalize latin\u003e is `true` (the default) do \u003courbigbook json/Latin normalization\u003e. This converts e.g. `é` to `e`.\n* if \u003courbigbook.json/id normalize punctuation\u003e is `true` (the default) do \u003courbigbook.json/Punctuation normalization\u003e. This converts e.g. `+` to `plus`.\n* convert consecutive sequences of all non `a-z0-9` ASCII characters to a single hyphen `-`. Note that this leaves non-ASCII characters untouched.\n* strip leading or trailing hyphens\nNote how those rules leave non-ASCII Unicode characters untouched, except for:\n* capitalization changes wher applicable, e.g. `É` to `é`\nas capitalization and determining if something \"is a letter or not\" in those cases can be tricky.\n\nFor toplevel headers, see: \u003cthe ID of the first header is derived from the filename\u003e.\n\nSo for example, the following automatic IDs would be generated: \u003ctable Examples of automatically generated IDs\u003e.\n\n\\Table[\n|| title\n|| id\n|| latin normalization\n|| punctuation normalization\n|| comments\n\n| My favorite title\n| my-favorite-title\n|\n|\n|\n\n| Ciro's markdown is awesome\n| ciro-s-markdown-is-awesome\n|\n|\n| `'` is an ASCII character, but it is not in `a-z0-9`, therefore it gets converted to a hyphen `-`\n\n| É你\n| e你\n| true\n|\n| The Latin https://en.wikipedia.org/wiki/Acute_accent[acute accented] `e`, `É`, is converted to its lower case form `é` as per the \u003cJavaScript case conversion\u003e.\n\n  Then, due to \u003courbigbook.json/Latin normalization\u003e, `é` is converted to `e`.\n\n  The Chinese character `你` is left untouched as Chinese characters have no case, and no ASCII analogue.\n\n| É你\n| é你\n| false\n|\n| Same as the previous, but `é` is not converted to `e` since \u003courbigbook.json/Latin normalization\u003e is turned off.\n\n| C++ is great\n| c-plus-plus-is-great\n|\n| true\n| This is the effect of \u003courbigbook.json/Punctuation normalization\u003e.\n\n| I \\i[love] dogs.\n| i-love-dogs\n|\n|\n| `love` is extracted from the italic tags `\u003ci\u003elove\u003c/i\u003e` with \u003cid output format\u003e conversion.\n\n| β Centauri\n| beta-centauri\n|\n|\n| Our Latin normalization is amazing and knows Greek!\n]\n{title=Examples of automatically generated IDs}\n\nFor \u003cthe toplevel header\u003e[the toplevel header], its ID is derived from the basename of the OurBigBook file without extension instead of from the `title` argument.\n\nTODO:\n* maybe we should also remove some or all non-ASCII punctuation. All can be done with `\\\\p{IsPunctuation}`: https://stackoverflow.com/questions/13925454/check-if-string-is-a-punctuation-character but we need to check that we really want to remove all of them.\n\n= ID target from title\n{c}\n{parent=H synonym argument}\n\nThis conversion type is similar to \u003cAutomatic ID from title\u003e, but it is used in certain cases where we are targeting IDs rather than setting them, notably:\n* \u003c\\H parent argument\u003e\n* \u003c\\H child argument\u003e\n* \u003c\\H tag argument\u003e\n\n= `\\H` `title2` argument of a synonym header\n{parent=H synonym argument}\n\nUnlike \u003c\\H title2 argument\u003e, the synonym does not show up by default next to the title. This is because we sometimes want that, and sometimes not. To make the title appear, you can simply add an empty `title2` argument to the synonym header as in:\n``\n= GNU Debugger\n{c}\n\n= GDB\n{c}\n{synonym}\n{title2}\n\n= Quantum computing\n\n= Quantum computer\n{synonym}\n``\nwhich renders something like:\n``\n= GNU Debugger (GDB)\n\n= Quantum computing\n``\nNote how we added the synonym to the title only when it is not just a simple flexion variant, since `Quantum computing (Quantum computer)` would be kind of useless would be kind of useless.\n\n= `\\H` `tag` argument\n{c}\n{parent=H arguments}\n{tag=multiple argument}\n\n= Tag\n{synonym}\n\nSame as \u003c\\x child argument\u003e but in the opposite direction, e.g.:\n``\n== Mammal\n\n=== Bat\n{tag=flying-animal}\n\n=== Cat\n\n== Flying animal\n``\nis equivalent in every way to:\n``\n== Mammal\n\n=== Bat\n\n=== Cat\n\n== Flying animal\n{child=bat}\n``\n\nNaming rationale:\n* `parent` as the opposite of child is already taken to be then \"main parent\" via the \"\u003c\\H parent argument\u003e\"\n* we could have renamed the \u003c\\H child argument\u003e to `tags` as in \"this header tags that one\", but it would be a bit confusing `tags` vs `tag`\nSo `child` vs `tag` it is for now.\n\nYou generally want to use `tag` instead of the \u003c\\H child argument\u003e because otherwise some very large header categories are going to contain Huge lists of children, which is not very nice when editing.\n\nIt is possible to enforce the \u003c\\H child argument\u003e or the \u003c\\H tag argument\u003e in a given project with the \u003courbigbook.json/lint h-tag\u003e option.\n\n= `\\H` `title2` argument\n{parent=H arguments}\n{tag=multiple argument}\n\nThe `title2` argument can be given to any element that has the `title` argument.\n\nIts usage is a bit like the `description=` argument of \u003cimages\u003e, allowing you to add some extra content to the header without affecting its ID.\n\nUnlike `description=` however, `title2` shows up on all \u003c\\x full argument\u003e[`full`] references, including appearances in the \u003ctable of contents\u003e, which make it more searchable.\n\nIts primary use cases are:\n* give acronyms, or other short names names of fuller titles such as mathematical/programming notation\n\n  One primary reason to not use the acronyms as the main section name is to avoid possible ID ambiguities with other acronyms.\n* give the header in different languages\n\nFor example, given the OurBigBook input:\n``\n= Toplevel\n\nThe Toc follows:\n\n== North Atlantic Treaty Organization\n{c}\n{title2=NATO}\n\n\\x[north-atlantic-treaty-organization]\n\n\\x[north-atlantic-treaty-organization]{full}\n``\nthe rendered output looks like:\n``\n= Toplevel\n\nThe ToC follows:\n\n* North Atlantic Treaty Organization (NATO)\n\n== North Atlantic Treaty Organization (NATO)\n\nNorth Atlantic Treaty Organization\n\nSection 1. \"North Atlantic Treaty Organization (NATO)\"\n``\n\nRelated alternatives to `title2` include:\n* \u003c\\H disambiguate argument\u003e when you do want to affect the ID to remove ambiguities\n* \u003c\\H synonym argument\u003e\n\nParenthesis are added automatically around all rendered `title2`.\n\nThe `title2` argument has a special meaning when applied to a \u003cheader\u003e with the \u003c\\H synonym argument\u003e, see \u003c\\H title2 argument of a synonym header\u003e.\n\n\\Comment[[\n= `\\H` `tutorial` argument\n{parent=h-arguments}\n{tag=boolean-argument}\n\nThis option is a convenience helper for the common use case of \"writting a tutorial\". The same would also apply to a report, or an article.\n]]\n\n= `\\H` `toplevel` argument\n{parent=H arguments}\n{tag=Boolean argument}\n\nWhen the `\\H` `toplevel` argument is set, the header and its descendants will be automatically output to a separate file, even without \u003c--split-headers\u003e.\n\nFor example given:\n\nanimal.bigb\n``\n= Animal\n\n== Vertebrate\n\n=== Dog\n{toplevel}\n\n==== Bulldog\n\n== Invertebrate\n``\n\nand if you convert as:\n``\nourbigbook animal.bigb\n``\nwe get the following output files:\n* `animal.html`: contains the headers: \"Animal\", \"Vertebrate\" and \"Invertebrate\", but not \"Dog\" and \"Bulldog\"\n* `dog.html`: contains only the headers: \"Dog\" and \"Bulldog\"\n\nThis option is intended to produce output identical to using \u003cincludes\u003e and separate files, i.e. the above is equivalent to:\n\nanimal.bigb\n``\n= Animal\n\n== Vertebrate\n\n\\Include[dog]\n\n== Invertebrate\n``\n\ndog.bigb\n``\n= Dog\n{toplevel}\n\n== Bulldog\n``\n\nOr in other words: \u003cthe toplevel header\u003e of each source file gets `{toplevel}` set implicitly for it by default.\n\nThis design choice might change some day. Arguably, the most awesome setup is on in which source files and outputs are completely decoupled. \u003cOurBigBook Web\u003e also essentially wants this, as ideally we want to store one source per header there in each DB entry. We shall see.\n\n= `\\H` `wiki` argument\n{parent=H arguments}\n\nIf given, show a link to the Wikipedia article that corresponds to the header.\n\nIf a value is not given, automatically link to the Wiki page that matches the header exactly with spaces converted to underscores.\n\nHere is an example with an explicit wiki argument:\n\n``\n==== Tiananmen Square\n{wiki=Tiananmen_Square}\n``\n\nwhich looks like:\n\n= Tiananmen Square\n{id=wiki-explicit}\n{parent=H wiki argument}\n{wiki=Tiananmen_Square}\n\nor equivalently with the value deduced from the title:\n\n``\n= Tiananmen Square\n{wiki}\n``\n\nwhich looks like:\n\n= Tiananmen Square\n{id=wiki-implicit}\n{parent=H wiki argument}\n{wiki}\n\nYou can only link to subsections of wiki pages with explicit links as in:\n\n``\n= History of Tiananmen Square\n{{wiki=Tiananmen_Square#History}}\n``\n\nwhich looks like:\n\n= History of Tiananmen Square\n{id=wiki-explicit-subsection}\n{parent=H wiki argument}\n{{wiki=Tiananmen_Square#History}}\n\nNote that in this case, you either need a \u003cliteral argument\u003e `{{}}` or to explicitly escape the `#` character as in:\n``\n= History of Tiananmen Square\n{wiki=Tiananmen_Square\\#History}\n``\nto avoid the creation of an \u003cinsane topic link with a single word\u003e.\n\nAlso note that Wikipedia subsections are not completely stable, so generally you would rather want to link to a permalink with a full URL as in:\n``\n= Artificial general intelligence\n{wiki=https://en.wikipedia.org/w/index.php?title=Artificial_general_intelligence\u0026oldid=1192191193#Tests_for_human-level_AGI}\n``\nNote that in this case escaping the `#` is not necessary because it is part of the \u003cinsane\u003e \u003clink\u003e that starts at `https://`.\n\n= Header metadata section\n{parent=Header}\n\nOurBigBook adds some header metadata to the toplevel header at the bottom of each page. This section describes this metadata.\n\nAlthough the \u003ctable of contents\u003e has a macro to specify its placement, it is also automatically placed at the bottom of the page, and could be considered a header metadata section.\n\n= Incoming links\n{parent=Header metadata section}\n\nLists other sections that link to the current section.\n\nE.g. in:\n``\n= tmp\n\n== tmp 1\n\n=== tmp 1 1\n\n=== tmp 1 2\n\n\\x[tmp-1]\n\n== tmp 2\n\n\\x[tmp-1]\n``\nthe page `tmp-1.html` would contain a list of incoming links as:\n* `tmp-1-2`\n* `tmp-2`\nsince those pages link to the `tmp-1` ID.\n\n= Tagged\n{parent=Header metadata section}\n\nLists sections that are \u003csecondary children\u003e of the current section, i.e. tagged under the current section.\n\nThe main header tree hierarchy descendants already show under the \u003ctable of contents\u003e instead.\n\nE.g. in:\n``\n= tmp\n\n== Mammal\n\n== Flying\n\n== Animal\n\n=== Bat\n{tag=mammal}\n{tag=flying}\n\n=== Bee\n{tag=flying}\n\n=== Dog\n{tag=mammal}\n``\nthe tagged sections for:\n* Mammal will contain Bat and Dog\n* Flying will contain Bat and Bee\n\n= Ancestors\n{parent=Header metadata section}\n\nShows a list of ancestors of the page. E.g. in:\n``\n= Asia\n\n== China\n\n=== Beijing\n\n==== Tiananmen Square\n\n=== Hong Kong\n``\nthe ancestor lists would be for:\n* Hong Kong: China, Asia\n* Tiananmen Square: Beijing, China, Asia\n* Beijing: China, Asia\n* China: Asia\nso we see that this basically provides a type of breadcrumb navigation.\n\n= Horizontal rule\n{parent=Macro}\n{title2=`\\Hr`}\n{tag=Implemented by sidstuff}\n\nUsed to represent a thematic break between paragraph-level elements:\n\\OurBigBookExample[[\nShe pressed the button. Just like that, everything was over.\n\n\\Hr\n\nThe next morning was a gloomy one. Nobody said a word.\n]]\n\nThis macro corresponds to a misfeature of HTML/Markdown, and is not encouraged. We instead recommend creating smaller more specific \u003cheaders\u003e instead to split sections, as this has all the usual advantages of allowing metadata to be associated to the header, such as \u003csplit headers\u003e, \u003ctopic\u003e, liked and discussions.\n\nBut they people asked, and they got it.\n\n= Image\n{parent=Macro}\n{title2=`\\Image` and `\\image`}\n\n= `\\Image` macro\n{synonym}\n\nA block image with \u003cblock vs inline macros\u003e[capital] 'i' `Image` showcasing most of the image properties \u003cimage my test image\u003e.\n\\OurBigBookExample[[\nHave a look at this amazing image: \\x[image-my-test-image].\n\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]\n{title=The title of my image}\n{id=image-my-test-image}\n{width=600}\n{height=200}\n{source=https://en.wikipedia.org/wiki/File:Tianasquare.jpg}\n{description=The description of my image.}\n]]\nThis exemplifies the following parameters:\n* `title`: analogous to the \u003c\\H title argument\u003e. Shows up preeminently, and sets a default ID if one is not given. It is recommended that you don't add a period `.` to it, as that would show in \u003ccross references\u003e\n* \u003cimage `description` argument\u003e\n* \u003cimage `source` argument\u003e[`source`]: a standardized way to credit an image by linking to a URL that contains further image metadata\nFor further discussion on the effects of ID see: \u003cimage ID\u003e{full}.\n\nAnd this is how you make an \u003cinline image\u003e inline one with lower case `i`:\n\\OurBigBookExample[[My inline \\image[Tank_man_standing_in_front_of_some_tanks.jpg][test image] is awesome.]]\n\u003cInline images\u003e can't have captions.\n\nAnd now for an image outside of \u003c\\OurBigBookExample\u003e to test how it looks directly under \u003ctoplevel\u003e: \u003cimage my test image toplevel\u003e{full}.\n\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]\n{id=image-my-test-image-toplevel}\n\n= Image ID\n{parent=Image}\n\nHere is an image without a \u003cimage description argument\u003e[description] but with an ID so we can link to it: \u003cimage my test image 2\u003e.\n\\OurBigBookExample[[\nHave a look at this amazing image: \\x[image-my-test-image-2].\n\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]\n{id=image-my-test-image-2}\n]]\nThis works because \u003c\\x full argument\u003e[`full` is the default cross reference style for `Image`], otherwise the link text would be empty since there is no `title`, and OurBigBook would raise an error.\n\nOurBigBook can optionally deduce the title from the basename of the `src` argument if the `titleFromSrc` \u003cboolean argument\u003e is given, or if `title-from-src` is set as the default \u003courbigbook.json/media-providers\u003e[media provider] for the media type:\n\\OurBigBookExample[[\nHave a look at this amazing image: \\x[image-tank-man-standing-in-front-of-some-tanks].\n\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]\n{titleFromSrc}\n]]\n\n= Image caption\n{parent=Image ID}\n\nIf the image has neither \u003cimage ID\u003e[ID] nor title nor \u003cimage description argument\u003e[description] nor `source`, then it does not get a caption at all:\n\\OurBigBookExample[[\\Image[Tank_man_standing_in_front_of_some_tanks.jpg\\]]]\n\nIf the image does not have an ID nor title, then it gets an automatically generated ID, just like every other OurBigBook output HTML element, and it is possible for readers to link to that ID on the rendered version, e.g. as:\n``\n#_123\n``\nNote that the `123` is not linked to the `Figure \u003cnumber\u003e.`, but just a sequential ID that runs over all elements.\n\nThis type of ID is of course not stable across document revisions however, since if an image is added before that one, the link will break. So give an ID or title for anything that you expect users to link to.\n\nAlso, it is not possible to link to such images with an \u003ccross reference\u003e, like any other OurBigBook element with autogenerated temporary IDs.\n\nAnother issue to consider is that in paged output formats like PDF, the image could float away from the text that refers to the image, so you basically always want to refer to image by ID, and not just by saying \"the following image\".\n\nWe can also see that such an image does not increment the Figure count:\n\\OurBigBookExample[[\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]{id=image-my-test-image-count-before}\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]{id=image-my-test-image-count-after}\n]]\n\nIf the image has any visible metadata such as `source` or `description` however, then the caption does show and the Figure count gets incremented:\n\\OurBigBookExample[[\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]{source=https://en.wikipedia.org/wiki/File:Tianasquare.jpg}\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]{description=This is the description of my image.}\n]]\n\n= Where to store images\n{parent=Image}\n\n= Store images inside the repository itself\n{parent=Where to store images}\n\nIf you are making a limited repository that will not have a ton of images, then you can get away with simply git tracking your images in the main repository.\n\nWith this setup, no further action is needed. For example, with a file structure of:\n``\n./README.bigb\n./Tank_man_standing_in_front_of_some_tanks.jpg\n``\njust use the image from `README.bigb` as:\n\\OurBigBookExample[[\n\\Image[Tank_man_standing_in_front_of_some_tanks.jpg]\n]]\n\nHowever, if you are making a huge tutorial, which can have a huge undefined number of images (i.e. any scientific book), then you likely don't want to git track your images in the git repository.\n\nA generally better alternative is to \u003cstore images in a separate media repository\u003e, and especially \u003cstore images in a separate media repository and track it as a git submodule\u003e.\n\n= Store images in a separate media repository\n{parent=Where to store images}\n\nIn this approach, you create a separate GitHub repository in addition to the main one containing the text to contain only media such as images.\n\nThis approach is more suitable than \u003cstore images inside the repository itself\u003e if you are going to have a lot of images.\n\nWhen using this approach, you could of course just point directly to the final image URL, e.g. as in:\n\\OurBigBookExample[[\n\\Image[https://raw.githubusercontent.com/ourbigbook/ourbigbook-media/master/Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png]\n]]\nbut OurBigBook allows you use configurations that allow you to enter just the image basename: `Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png` which we will cover next.\n\nIn order to get this to work, the recommended repository setup is:\n* `./main-repo/.git`: main repository at https://github.com/username/main-repo\n* `./main-repo/data/media/.git/`: media repository at https://github.com/username/main-repo-media[], and where `data/` is gitignored.\nThe directory and repository names are not mandatory, but if you place media in `data/media` and name its repository by adding the `*-media` suffix, then `ourbigbook` will handle everything for you without any further configuration in \u003courbigbook.json/media-providers\u003e.\n\nThis particular documentation repository does have a different setup as can be seen from its \\a[ourbigbook.json]. Then, when everything is setup correctly, we can refer to images simply as:\n\\OurBigBookExample[[\n\\Image[Fundamental_theorem_of_calculus_topic_page_arrow_to_full_article.png]{provider=github}\n]]\nIn this example, we also needed to set `{provider=github}` explicitly since it was not set as the default image provider in our `ourbigbook.json`. In most projects however, all of your images will be in the default repository, so this won't be needed.\n\n`provider` must not be given when a full URL is given because we automatically detect providers from URLs, e.g.:\n``\n\\Image[https://raw.githubusercontent.com/ourbigbook/ourbigbook-media/master/Fundamental_theorem_of_calculus_topic_page.png]{provider=github}\n``\nis an error.\n\nTODO implement: `ourbigbook` will even automatically add and push used images in the `my-tutorial-media` repository for you \u003cstatic website\u003e[during publishing]!\n\nYou should then use the following rules inside `my-tutorial-media`:\n* give every file a very descriptive and unique name as a full English sentence\n* never ever delete any files, nor change their content, unless it is an improvement in format that does change the information contained of the image TODO link to nice Wikimedia Commons guideline page\nThis way, even though the repositories are not fully in sync, anyone who clones the latest version of the `*-media` directory will be able to view any version of the main repository.\n\nThen, if one day the media repository ever blows up GitHub's limit, you can just migrate the images to another image server that allows arbitrary basenames, e.g. AWS, and just configure your project to use that new media base URL with the \u003courbigbook.json/media-providers\u003e option.\n\nThe reason why images should be kept in a separate repository is that images are hundreds or thousands of times larger than hand written text.\n\nTherefore, images could easily fill up the maximum repository size you are allowed: https://webapps.stackexchange.com/questions/45254/file-size-and-storage-limits-on-github#84746 and then what will you do when GitHub comes asking you to reduce the repository size?\n\nhttps://git-lfs.github.com/[Git LFS] is one approach to deal with this, but we feel that it adds too much development overhead.\n\n= Store images in a separate media repository and track it as a git submodule\n{parent=Store images in a separate media repository}\n\nThis is likely the sanest approach possible, as it clearly specifies which media version matches which repository version through the submodule link.\n\nFurthermore, 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`.\n\nThen, add to \u003courbigbook.json/media-providers\u003e:\n``\n\"media-providers\": {\n  \"github\": {\n    \"default-for\": [\"image\", \"video\"],\n    \"path\": \"media\",\n    \"remote\": \"yourname/myproject-media\"\n  }\n}\n``\n\nNow, as mentioned at \u003courbigbook.json/media-providers\u003e, everything will work beautifully:\n\n* `ourbigbook .` local conversion will use images from `media/` if it exists, e.g.:\n  ``\n  \\Image[myimage.jpg]\n  ``\n  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.\n\n  But if the submodule is not cloned, not problem, renders will detect that and automatically use GitHub images.\n\n  Then, when you do:\n  ``\n  ourbigbook --publish\n  ``\n  the following happen:\n  * `\\Image[myimage.jpg]` uses the GitHub URL\n  * automatically push `media/` to GitHub in case there were any updates\n  * also, that directory is automatically gitignore, so it won't be pushed as part of the main render and thus duplicate things\n\n= Store images in Wikimedia Commons\n{parent=Where to store images}\n\nWikimedia Commons is another great possibility to upload your images to:\n\\OurBigBookExample[[\n\\Image[https://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/Gel","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fourbigbook%2Fourbigbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fourbigbook%2Fourbigbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fourbigbook%2Fourbigbook/lists"}