iskm/learnxinyminutes-docs
1
0
Fork 0
mirror of https://github.com/adambard/learnxinyminutes-docs.git synced 2025-04-26 15:13:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[asciidoc/en] Added more examples and updated information

Browse Source 
Added comments, document attributes, code blocks, images, tables,
hyperlinks, text replacements, includes, horizontal rule, Syntax Quick
Reference
This commit is contained in:
MykBamberg 2025-04-17 17:25:54 +02:00
parent 7f0f27d84d
commit a9df2fc4ca
1 changed files with 126 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
asciidoc.md
View File

@ -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 <h5>
```
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 <stdio.h>
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/[]
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/)