Captain Lugaru

I am a coding Viking Bunny. In 2021 I won internship at ASE Inc.

Book 1: Introduction to AsciiDoc

AsciiDoc is a lightweight markup language used for writing structured documents. It is often used for technical documentation, books, articles, and presentations. Unlike Markdown, AsciiDoc has more advanced formatting options, making it a powerful choice for documentation. For many years, the default standard for formal scientific documentation was LaTeX. Which is complex, requires many tools, and is riddled with rendering issues. Asciidoctor is a tool for converting AsciiDoc to HTML, PDF, and other formats. And together, the language and the simple tool helped AsciiDoc become the new standard.

Why Use AsciiDoc?

  • Readable and simple: Use plain text with intuitive syntax.

  • Highly structured: Supports complex documents, (books, manuals, reports).

  • Flexible output formats Can be converted to HTML, PDF, DocBook, and more.

  • Powerful features Include tables, code blocks, images, cross-references, and variables.

  • Used in professional documentation: Companies like Red Hat and GitHub use it for documentation.

Differences Between AsciiDoc, Markdown, and LaTeX

Feature AsciiDoc Markdown LaTeX

Syntax Simplicity

Easy

Very Easy

Complex

Output Formats

HTML, PDF, DocBook

HTML, PDF

PDF, PostScript

Tables Support

Yes

Limited

Yes

Variables & Attributes

Yes

No

Yes

Ideal for

Technical Docs, Books

Blog Posts, Notes

Academic Papers

AsciiDoc is more powerful than Markdown for documentation but simpler than LaTeX. It supports tables, variables, and multiple output formats, making it a great choice for structured documents.

Installing AsciiDoc Tools

Before writing AsciiDoc documents, you need tools to preview and convert them. Choose one of the following:

Open a terminal or command prompt. Run:

gem install asciidoctor

Verify installation:

asciidoctor --version

Use an Online AsciiDoc Editor

Websites like https://asciidoclive.com/ allow you to write and preview AsciiDoc without installing anything.

AsciiDoc Plugins for Editors

  • VS Code: Install the AsciiDoc extension.

  • Atom: Use the asciidoc-preview package.

Writing Your First AsciiDoc File

Create a new file named example.adoc. Add the following content:

= My First AsciiDoc Document
:author: Your Name
:revdate: 2025-02-21

This is my first AsciiDoc document.

== Introduction

AsciiDoc allows you to write structured documents easily.

== Features

- Simple markup
- Converts to multiple formats
- Supports advanced formatting

Save the file and convert it to HTML using:

asciidoctor example.adoc

Open example.html in a web browser to see the formatted document.

Book 2: Basic Formatting

Paragraphs and Line Breaks

  • To create a new paragraph, simply start typing on a new line.

  • To force a line break within a paragraph, use a + at the end of the line.

Example:

This is a line with a forced break. +
This text appears on a new line.

Headings

  • Use = for the document title, == for sections, and more === for subsections.

Example:

= Main Title
== Section 1
=== Subsection 1.1

Bold, Italic, and Underline

  • Bold: bold → bold

  • Italic: italic → italic

  • Underline: underlined → underlined

Monospace and Inline Code

  • Use backticks for inline code: Inline code example

  • Use ` to mark text as monospace: `+monospace text

Lists

Unordered List

  • First item

  • Second item

    • Sub-item

Ordered List

  1. First item

  2. Second item

    1. Sub-item

Description List

AsciiDoc

A markup language.

Markdown

A simpler markup language.

Book 3: Structuring a Document

Document Title and Metadata

Example:

= Document Title
Author Name
2025-02-21
:doctype: article (could be used for books and other things)
:toc: preamble (table of contents)

Sections and Subsections

Example:

== Introduction
=== Subsection 1
==== Sub-subsection

Including External Files

Syntax:

// include::file.adoc[]
// This is commented so that the file doesnt create issues

Comments in AsciiDoc

Syntax:

// This is a comment

Book 4: Advanced Formatting

Block Quotes

Syntax:

[quote, Author Name, Book Title]
____
This is a block quote.
____
[sidebar]
****
This is a sidebar.
****

Admonitions

NOTE: This is an important note.
TIP: This is a useful tip.
WARNING: Be careful with this!

Source Code Blocks

Example:

def hello():
    print("Hello, AsciiDoc!")
// this is commented out to not break anything
 ----

Tables

Basic Table

|===
| Column 1 | Column 2 | Column 3
| Row 1A   | Row 1B   | Row 1C
| Row 2A   | Row 2B   | Row 2C
|===

CSV-Style Table

[format="csv"]
|===
Column 1,Column 2,Column 3
Row 1A,Row 1B,Row 1C
Row 2A,Row 2B,Row 2C
|===

Adding Images

Syntax:

// image::image.jpg[Alt Text, width=500]
https://www.example.com[Visit Example]
// <<introduction, Go to Introduction>> this is commented out to not cause any issues

Cross-References in a Document

Creating a Reference Target

[[section-id]]== My Section Title

Linking to the Section

// <<section-id, Read more here>> this is commented out to not cause any issues

Book 6: A Demo Document — How a Volcano Once Blocked Out the Sun (1816: The Year Without a Summer)

Introduction of calamity

The year 1816 is often remembered as The Year Without a Summer, a time of extreme weather anomalies that led to global crop failures, food shortages, and social unrest. The root cause?
The massive eruption of *Mount Tambora [1]*in April 1815, one of the most powerful volcanic eruptions in recorded history. This catastrophic event sent enormous amounts of volcanic ash and sulfur dioxide into the atmosphere, dramatically altering the Earth’s climate for over a year.

Mount Tambora Eruption

The Eruption of Mount Tambora (April 1815)

Mount Tambora[1], located in present-day Indonesia, erupted with an estimated Volcanic Explosivity Index (VEI)[2] of 7, making it the largest eruption in at least 1,300 years. The explosion ejected about 100 cubic kilometers of volcanic material into the atmosphere, killing tens of thousands in the immediate aftermath. However, the most significant and far-reaching consequences were atmospheric:

— A vast cloud of ash and sulfur dioxide spread across the globe, blocking sunlight.+

— Global temperatures dropped by an estimated 0.4–0.7°C (0.7–1.3°F) over the next year.+

— Acid rain and ashfall disrupted agriculture and ecosystems.

The Tambora eruption was 100 times more powerful than Mount St. Helen’s in 1980.

1816: A year without a summer

As a result of Tambora’s eruption, the Northern Hemisphere experienced a dramatic climate shift in 1816, leading to unseasonably cold temperatures, failed harvests, and widespread famine. Some of the most significant effects were:

— Frost in Summer: Snow fell in June in parts of New England and Canada, and frosts occurred as far south as Virginia.

— Crop Failures: Europe and North America saw wheat, corn, and other crops fail, causing food shortages and skyrocketing prices.

— Famine and Disease: With food scarcity came malnutrition, and diseases like typhus and cholera spread rapidly.

— Mass Migration: Many Americans, unable to farm, moved westward in search of better conditions, speeding up U.S. expansion.

Cultural and Scientific Advancements

The Year Without a Summer also had unexpected cultural effects:

— Mary Shelley’s Frankenstein[3]* – In 1816, a group of writers, including Mary Shelley, were trapped indoors due to the gloomy weather while vacationing in Switzerland. This eerie atmosphere inspired the creation of Frankenstein, a story that would become one of the most famous Gothic novels of all time.

— Invention of the Bicycle – Crop failures led to the death of many horses, prompting German inventor Karl Drais[4]* to develop the Laufmaschine[4]*, an early prototype of the modern bicycle.

A warning from history

The 1816 climate crisis is a reminder of how volcanic activity can significantly impact global weather patterns. While modern science allows us to predict and mitigate some effects, a similar eruption today would still pose severe risks to global food supply and economies.

Timeline of Events

Year Event

1815

Mount Tambora erupts, sending ash into the atmosphere.

1816

The Year Without a Summer – global temperatures drop.

1816

Snow falls in New England in June.

1816

Widespread famine leads to mass migration in Europe and America.

1816

Mary Shelley begins writing Frankenstein.

1817

Karl Drais invents the Laufmaschine due to horse shortages.

Conclusion

The Year Without a Summer was a direct result of the Mount Tambora eruption, demonstrating how a single geological event can reshape human history. From global famine to literary inspiration, its effects were profound and far-reaching. Understanding these historical climate anomalies can help us prepare for future environmental disruptions.

1. Mount Tambora is a stratovolcano located on Sumbawa Island, Indonesia. Before the 1815 eruption, it stood about 4,300 meters (14,100 feet) high, but the eruption reduced its height to about 2,850 meters (9,350 feet).
2. The Volcanic Explosivity Index (VEI) is a scale that measures the explosiveness of volcanic eruptions. It ranges from 0 (non-explosive) to 8 (super-colossal). The Tambora eruption was rated VEI-7, meaning it was one of the most powerful eruptions in the last 10,000 years.
3. Mary Shelley wrote Frankenstein in 1816 while staying in Geneva, Switzerland, with a group of writers including Lord Byron and Percy Bysshe Shelley. The eerie weather conditions influenced the novel’s dark and stormy themes.
4. Due to widespread crop failures in 1816, horses became scarce as people could not afford to feed them. German inventor Karl Drais created the *Laufmaschine, an early version of the modern bicycle, as an alternative mode of transport.

Updated:

You may also enjoy