mirror of
https://github.com/foo-dogsquared/hugo-theme-contentful.git
synced 2025-01-31 10:58:07 +00:00
380 lines
13 KiB
HTML
380 lines
13 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en-us"><title>Asciidoctor Extended Syntax Guide</title>
|
||
<link rel="stylesheet" href="https://foo-dogsquared.github.io/hugo-theme-contentful/css/main.min.ac4668a81007ca38fcac8e88436ad4fa6a969ee4ce9352f52f795abf04e1624a.css" /><meta name="generator" content="Hugo 0.76.0" />
|
||
<meta charset="utf-8">
|
||
<meta name="author" content="" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta name="referrer" content="no-referrer" />
|
||
<meta name="description" content="The purpose of this article to make sure not-so-common features of Asciidoctor (i.e. admonition blocks, callouts) are styled and fit to the theme. It also serves as a quick introduction to more Asciidoctor as well. Feel free to steal this if you want a template for this.
|
||
Admonition blocks Admonition blocks contain content that are not a part of the main content but you’ll want to draw attention to the audience anyways." /><meta name="twitter:card" content="summary"/>
|
||
<meta name="twitter:title" content="Asciidoctor Extended Syntax Guide"/>
|
||
<meta name="twitter:description" content="The purpose of this article to make sure not-so-common features of Asciidoctor (i.e. admonition blocks, callouts) are styled and fit to the theme. It also serves as a quick introduction to more Asciidoctor as well. Feel free to steal this if you want a template for this.
|
||
Admonition blocks Admonition blocks contain content that are not a part of the main content but you’ll want to draw attention to the audience anyways."/>
|
||
<meta property="og:title" content="Asciidoctor Extended Syntax Guide" />
|
||
<meta property="og:description" content="The purpose of this article to make sure not-so-common features of Asciidoctor (i.e. admonition blocks, callouts) are styled and fit to the theme. It also serves as a quick introduction to more Asciidoctor as well. Feel free to steal this if you want a template for this.
|
||
Admonition blocks Admonition blocks contain content that are not a part of the main content but you’ll want to draw attention to the audience anyways." />
|
||
<meta property="og:type" content="article" />
|
||
<meta property="og:url" content="https://foo-dogsquared.github.io/hugo-theme-contentful/articles/asciidoctor-extended-syntax-guide/" />
|
||
<meta property="article:published_time" content="2019-08-29T22:09:16+08:00" />
|
||
<meta property="article:modified_time" content="2020-05-12T16:40:21+08:00" />
|
||
<link rel="canonical" type="text/html" href="https://foo-dogsquared.github.io/hugo-theme-contentful/articles/asciidoctor-extended-syntax-guide/" />
|
||
|
||
<script>
|
||
const theme = window.localStorage.getItem('theme');
|
||
if (theme) {
|
||
document.documentElement.dataset.theme = theme;
|
||
}
|
||
</script>
|
||
<body><nav aria-label="Primary navigation">
|
||
<a class="site__title" href="https://foo-dogsquared.github.io/hugo-theme-contentful/">Contentful</a>
|
||
<div class="site__links">
|
||
|
|
||
<a href="https://foo-dogsquared.github.io/hugo-theme-contentful/about/">About</a> |
|
||
<a href="https://foo-dogsquared.github.io/hugo-theme-contentful/categories/">Categories</a> |
|
||
<a href="https://foo-dogsquared.github.io/hugo-theme-contentful/recipes/">Recipes</a> |
|
||
<a href="https://foo-dogsquared.github.io/hugo-theme-contentful/tags/">Tags</a> |
|
||
|
||
</div>
|
||
<button class="site__theme-btn" aria-label="theme-toggle" onclick="const theme = window.localStorage.getItem('theme') == 'dark' ? 'light' : 'dark'; window.localStorage.setItem('theme', theme); document.documentElement.dataset.theme = theme">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
|
||
<path d="M0 12c0 6.627 5.373 12 12 12s12-5.373 12-12-5.373-12-12-12-12 5.373-12 12zm2 0c0-5.514 4.486-10 10-10v20c-5.514 0-10-4.486-10-10z"></path>
|
||
</svg>
|
||
</button>
|
||
</nav>
|
||
|
||
|
||
<article>
|
||
<header>
|
||
<h1>Asciidoctor Extended Syntax Guide</h1>
|
||
</header>
|
||
<div class="post__meta">
|
||
|
||
|
||
|
||
<p data-content-publication-date="2019-08-29 22:09:16 +0800 +0800">Created: <time datetime="2019-08-29">2019-08-29</time></p>
|
||
|
||
|
||
<p data-content-modification-date="2020-05-12 16:40:21 +0800 +0800">Updated: <time datetime="2020-05-12">2020-05-12</time></p>
|
||
|
||
|
||
</div>
|
||
<hr>
|
||
|
||
|
||
|
||
<style>
|
||
#TableOfContents:not(:empty)::before {
|
||
content: "Table of contents";
|
||
font-weight: bold;
|
||
}
|
||
</style>
|
||
<nav id="TableOfContents">
|
||
<ul>
|
||
<li><a href="#_admonition_blocks">Admonition blocks</a></li>
|
||
<li><a href="#_callouts">Callouts</a></li>
|
||
<li><a href="#_passthroughs">Passthroughs</a></li>
|
||
</ul>
|
||
</nav>
|
||
|
||
|
||
<main>
|
||
|
||
<div id="preamble">
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>The purpose of this article to make sure not-so-common features of
|
||
Asciidoctor (i.e. admonition blocks, callouts) are styled and
|
||
fit to the theme.
|
||
It also serves as a quick introduction to more Asciidoctor as well.
|
||
Feel free to steal this if you want a template for this.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_admonition_blocks">Admonition blocks</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Admonition blocks contain content that are not a part of the main
|
||
content but you’ll want to draw attention to the audience anyways.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>By default, Asciidoctor provides five labels for admonitions:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code>TIP</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>NOTE</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>IMPORTANT</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>CAUTION</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>WARNING</code></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="sidebarblock">
|
||
<div class="content">
|
||
<div class="title"><code>CAUTION</code> vs <code>WARNING</code></div>
|
||
<div class="paragraph">
|
||
<p>As the <a href="https://asciidoctor.org/docs/user-manual/#admonition">user manual</a>
|
||
has said, <code>CAUTION</code> and <code>WARNING</code> should be used with different semantics.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>CAUTION</code> basically advises the user to observe care.
|
||
<code>WARNING</code> warns the user about the dangers or consequences that’ll exist.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Writing an admonition is intuitively easy, simply write the label
|
||
in all uppercase and append with a colon.
|
||
Then write the content after.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">TIP: Lorem ipsum dolor sit amet consectetur adipiscing elit varius cursus
|
||
orci nulla, fames nisl sodales scelerisque eu consequat sem imperdiet ac mi
|
||
vivamus tempor, accumsan ad justo odio viverra praesent senectus class egestas duis.</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>It’ll render as this:</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tbody><tr>
|
||
<td class="icon">
|
||
<div class="title">Tip</div>
|
||
</td>
|
||
<td class="content">
|
||
Lorem ipsum dolor sit amet consectetur adipiscing elit varius cursus
|
||
orci nulla, fames nisl sodales scelerisque eu consequat sem imperdiet ac mi
|
||
vivamus tempor, accumsan ad justo odio viverra praesent senectus class egestas duis.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In case you want to style the labels differently such as assigning
|
||
appropriate colors or an icon to the rest of the labels,
|
||
here’s the rest of them:</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tbody><tr>
|
||
<td class="icon">
|
||
<div class="title">Note</div>
|
||
</td>
|
||
<td class="content">
|
||
Malesuada mattis aenean ultrices netus cursus viverra vivamus ultricies,
|
||
velit molestie penatibus phasellus in ante luctus, habitant suspendisse eros
|
||
turpis taciti risus himenaeos.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</div>
|
||
<div class="admonitionblock important">
|
||
<table>
|
||
<tbody><tr>
|
||
<td class="icon">
|
||
<div class="title">Important</div>
|
||
</td>
|
||
<td class="content">
|
||
Velit fringilla feugiat nibh id faucibus scelerisque facilisis ac,
|
||
suscipit quisque odio libero ullamcorper curabitur fames nascetur, elementum
|
||
tristique hac nisl etiam dictumst dapibus.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</div>
|
||
<div class="admonitionblock caution">
|
||
<table>
|
||
<tbody><tr>
|
||
<td class="icon">
|
||
<div class="title">Caution</div>
|
||
</td>
|
||
<td class="content">
|
||
Tempus dui aptent tempor torquent lacinia sem cursus porta cras semper
|
||
accumsan feugiat, himenaeos mi ullamcorper pharetra enim class eget auctor conubia
|
||
metus curabitur.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tbody><tr>
|
||
<td class="icon">
|
||
<div class="title">Warning</div>
|
||
</td>
|
||
<td class="content">
|
||
Aliquet ut maecenas mollis id enim nibh suscipit quisque posuere cum fusce,
|
||
dignissim ad curabitur odio ac diam pharetra platea vivamus eleifend.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_callouts">Callouts</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Callouts are used to add annotations within a verbatim block.
|
||
This is especially useful for code listings in order to effectively explain what
|
||
is going on within the code.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Here’s an example of using callouts.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">[source,python]
|
||
----
|
||
from pathlib import Path
|
||
from re import compile, match
|
||
|
||
current_directory = Path(".") <1>
|
||
notes_directory = current_directory / "notes/" <2>
|
||
----
|
||
<1> Created a Path object
|
||
<2> Appending a Path object with "/"</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>And it’ll render as:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight"><code class="language-python" data-lang="python">from pathlib import Path
|
||
from re import compile, match
|
||
|
||
current_directory = Path(".") # <b class="conum">(1)</b>
|
||
notes_directory = current_directory / "notes/" # <b class="conum">(2)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<ol>
|
||
<li>
|
||
<p>Created a <code>Path</code> object</p>
|
||
</li>
|
||
<li>
|
||
<p>Appending a <code>Path</code> object with "/"</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>One of the most important you should style is the callout number
|
||
on the code listings block.
|
||
Normally, when a user wants to copy-paste (even though I don’t personally
|
||
encourage it), the callout number gets in the way and they have to
|
||
manually remove them which can be annoying.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Either attach the property <code>user-select</code> with it or take a part from the
|
||
default Asciidoctor stylesheet and include it in your own stylesheet.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_passthroughs">Passthroughs</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>A <a href="https://asciidoctor.org/docs/user-manual/#passthroughs">passthrough</a> passes the input as it is on the final output.
|
||
This is useful for web-based outputs, for example passing raw HTML for interactive scripts or to create a live result.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Below is a very simple example with a <a href="https://p5js.org/">p5.js</a> sketch.</p>
|
||
</div>
|
||
<div id="example-sketch"></div>
|
||
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.0.0/p5.js"></script>
|
||
<script>
|
||
const sketchuuuuu = ( sketch ) => {
|
||
let x = 100;
|
||
let y = 100;
|
||
|
||
sketch.setup = () => {
|
||
sketch.createCanvas(300, 380);
|
||
};
|
||
|
||
sketch.draw = () => {
|
||
sketch.background(0);
|
||
sketch.fill(255);
|
||
sketch.rect(x,y,50,50);
|
||
sketch.ellipse(sketch["mouseX"], sketch["mouseY"], 20);
|
||
};
|
||
};
|
||
|
||
let example_sketch = new p5(sketchuuuuu, "example-sketch")
|
||
</script>
|
||
<div class="paragraph">
|
||
<p>Here is the input from the source code of this document.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight"><code class="language-asciidoctor" data-lang="asciidoctor">++++
|
||
<div id="example-sketch"></div>
|
||
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.0.0/p5.js"></script>
|
||
<script>
|
||
const sketchuuuuu = ( sketch ) => {
|
||
let x = 100;
|
||
let y = 100;
|
||
|
||
sketch.setup = () => {
|
||
sketch.createCanvas(300, 380);
|
||
};
|
||
|
||
sketch.draw = () => {
|
||
sketch.background(0);
|
||
sketch.fill(255);
|
||
sketch.rect(x,y,50,50);
|
||
sketch.ellipse(sketch["mouseX"], sketch["mouseY"], 20);
|
||
};
|
||
};
|
||
|
||
let example_sketch = new p5(sketchuuuuu, "example-sketch")
|
||
</script>
|
||
++++</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This is the closest instance of <a href="https://en.wikipedia.org/wiki/Literate_programming">literate programming</a> in the web when using Asciidoctor.
|
||
(Sadly, not as flexible or cool as <a href="https://orgmode.org/">Org-Mode</a> or <a href="https://jupyter.org/">Jupyter Notebooks</a>.)</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</main>
|
||
</article>
|
||
|
||
<hr>
|
||
<footer>
|
||
|
||
<p><a href="https://foo-dogsquared.github.io/hugo-theme-contentful/">Back to home</a></p>
|
||
</footer>
|
||
|
||
|
||
|
||
<p>Available in other languages:
|
||
<span class="site__languages">|
|
||
|
||
<a href="/hugo-theme-contentful/en">English</a> |
|
||
|
||
<a href="/hugo-theme-contentful/tl">Tagalog</a> |
|
||
|
||
</span>
|
||
</p>
|
||
|
||
|
||
|
||
<p>© 2021 Contentful</p>
|
||
</body>
|
||
</html>
|