From a9df2fc4ca92ef0400c785a12eb3d4e6d4ea3f04 Mon Sep 17 00:00:00 2001 From: MykBamberg Date: Thu, 17 Apr 2025 17:25:54 +0200 Subject: [PATCH] [asciidoc/en] Added more examples and updated information Added comments, document attributes, code blocks, images, tables, hyperlinks, text replacements, includes, horizontal rule, Syntax Quick Reference --- asciidoc.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 126 insertions(+), 13 deletions(-) diff --git a/asciidoc.md b/asciidoc.md index 91ef2704..965e9ef0 100644 --- a/asciidoc.md +++ b/asciidoc.md @@ -3,12 +3,13 @@ name: AsciiDoc contributors: - ["Ryan Mavilia", "http://unoriginality.rocks/"] - ["Abel Salgado Romero", "https://twitter.com/abelsromero"] + - ["Mykolas Bamberg", "https://github.com/MykBamberg"] filename: asciidoc.adoc --- AsciiDoc is a markup language similar to Markdown and it can be used for anything from books to blogs. Created in 2002 by Stuart Rackham the language is simple but it allows for a great amount of customization. -Document Header +**Document Header** Headers are optional and can't contain blank lines. It must be offset from content by at least one blank line. @@ -48,18 +49,49 @@ v1.0, 2016-01-13 This article about chips is going to be fun. ``` -Paragraphs +**Comments** + +``` +// AsciiDoc offers line comments, beginning with a double slash + +//// +and block comments enclosed +by four-slash delimiters +which can span multiple lines +//// +``` + +**Built-in Document Attributes** + +``` += Document Title +// Document attributes change different behaviors of the document +// These are commonly used to +:imagesdir: ./images +:iconsdir: ./icons +// set resource directories, +:toc: +// enable an automatic table of contents, +:notitle: +// hide the document title, +:sectnums: +// automatically number document sections, +:source-highlighter: pygments +// set a source code highlighter +``` + +**Paragraphs** ``` You don't need anything special for paragraphs. Add a blank line between paragraphs to separate them. -To create a line blank add a + -and you will receive a line break! +To create a line break within a paragraph add a + +to the end of the line and you will receive a line break! ``` -Formatting Text +**Formatting Text** ``` _underscore creates italics_ @@ -67,9 +99,11 @@ _underscore creates italics_ *_combine for extra fun_* `use ticks to signify monospace` `*bolded monospace*` +"`double curved quotes`" +'`single curved quotes`' ``` -Section Titles +**Section Titles** ``` = Level 0 (may only be used in document's header) @@ -83,9 +117,9 @@ Section Titles ===== Level 4
``` -Lists +**Lists** -To create a bulleted list use asterisks. +To create an unordered list use asterisks. ``` * foo @@ -93,7 +127,7 @@ To create a bulleted list use asterisks. * baz ``` -To create a numbered list use periods. +To create an ordered list use periods. ``` . item 1 @@ -117,15 +151,94 @@ You can nest lists by adding extra asterisks or periods up to five times. ..... foo 5 ``` +**Source Code Blocks** + +``` +[source,c] +---- +#include + +int main(void) { + printf("AsciiDoc source code blocks are rendered" + "in a fixed-width font with syntax highlighting\n"); +} +---- +``` + +**Images** + +``` +image::image.png[] + +.Figure caption +image::image.png["Alt text",128,128] +``` + +**Tables** + +``` +// The cols attribute specifies the number and relative width of each +// column. In this case there are two columns with the first having +// Twice the width of the latter. +[cols="2,1"] +|=== +|column 1, row 1 +|column 2, row 1 + +|column 1, row 2 +|column 2, row 2 +|=== +``` + +**Hyperlinks** + +``` +https://learnxinyminutes.com/ + + + +https://learnxinyminutes.com/[] + +https://learnxinyminutes.com/[Learn X in Y minutes] +``` + +**Text replacements** + +Some character sequences are replaced by appropriate Unicode characters + +``` +* Copyright: (C) +* Registered: (R) +* Trademark: (TM) +* Em dash: -- +* Ellipsis: ... +* Arrows: -> => <- <= +``` + +**Includes** + +Include another file's content in the document + +``` +include::other_asciidoc_file.adoc[] +``` + +**Horizontal Rule** + +``` +''' +``` + ## Further Reading -There are two tools to process AsciiDoc documents: +**Converters** -1. [AsciiDoc](http://asciidoc.org/): original Python implementation available in the main Linux distributions. Stable and currently in maintenance mode. -2. [Asciidoctor](http://asciidoctor.org/): alternative Ruby implementation, usable also from Java and JavaScript. Under active development, it aims to extend the AsciiDoc syntax with new features and output formats. +1. [Asciidoctor](http://asciidoctor.org/): Actively developed reference implementation in Ruby +2. [AsciiDoc.py](http://asciidoc.org/): Legacy implementation supporting an older syntax -Following links are related to `Asciidoctor` implementation: +**Helpful Resources** * [Markdown - AsciiDoc syntax comparison](http://asciidoctor.org/docs/user-manual/#comparison-by-example): side-by-side comparison of common Markdown and AsciiDoc elements. * [Getting started](http://asciidoctor.org/docs/#get-started-with-asciidoctor): installation and quick start guides to render simple documents. * [Asciidoctor User Manual](http://asciidoctor.org/docs/user-manual/): complete single-document manual with syntax reference, examples, rendering tools, amongst others. +* [AsciiDoc Syntax Quick Reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/)