Post on 22-Jan-2018
transcript
AsciidoctorNew, Noteworthy, & Beyond
A l e x S o t o R e d H a t @ a l e x s o t o b
Logo
Processor
Asciidoctor AsciiDoc
xrefstyle
Refer to <<foreign-keys>>.
...
=== Foreign Keys
Refer to Section 3.2, “Foreign Keys”.:xre
fsty
le: f
ull
Refer to Section 3.2.:xre
fsty
le: s
hort
Refer to <<foreign-keys>>.
...
=== Foreign Keys
Translations
data/locale/attributes-<lang>.adoc
ar bg ca da de es fa
� fr hu id it ja kr
nb nl nn pl pt pt_BR ro
ru sr sr_Latn tr uk zh_CN zh_TW
Tran
slat
ed a
ttrib
utes
:: fr
:appendix-caption: Appendice :appendix-refsig: {appendix-caption} :caution-caption: Avertissement :example-caption: Exemple :figure-caption: Figure :important-caption: Important :last-update-label: Dernière mise à jour ...
Advanced tag �ltering
Tagg
ed in
clud
e �l
epackage com.acme; //tag::named[] import javax.inject.Named; //end::named[] import javax.enterprise.context.RequestScoped;
//tag::named[] @Named("X") //end::named[] @RequestScoped public class TheBeanCalledX { ... }
java
---- include::TheBeanCalledX.java[tags=!*] ----
package com.acme; import javax.enterprise.context.RequestScoped;
@RequestScoped public class TheBeanCalledX { ... }
Excl
ude
all t
ags
package com.acme; import javax.enterprise.context.RequestScoped;
@RequestScoped public class TheBeanCalledX { ... }Ex
clud
e ta
gs b
y na
me ----
include::TheBeanCalledX.java[tags=!named] ----
---- include::TheBeanCalledX.java[tags=**] ----
package com.acme;
import javax.inject.Named; import javax.enterprise.context.RequestScoped;
@Named("X") @RequestScoped public class TheBeanCalledX { ... }
Incl
ude
ever
ythi
ng
Stronger SVG support
image::diagram.svg[opts=interactive]
<object type="image/svg+xml" data="diagram.svg"> <span class="alt">diagram</span> </object>
Inte
ract
ive
SVG
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 400" version="1.1"> <g>...</g> </svg>In
line
SVG image::diagram.svg[opts=inline]
Dia
gram
s in
SVG
… [plantuml,devoxx,svg,opts=inline] ---- start if (Going to Devoxx?) then (yes) : attend talks \n network \n drink beer; else (no) : watch talks \n live on YouTube \n (without pants); endif stop ----
Going to Devoxx?yes no
attend talks
network
drink beer
watch talks
live on YouTube
(without pants)
… mea
ns d
iagr
ams
are
cris
p
Compliance & stability
Asciidoctor Bespoke
Basi
c pr
esen
tatio
n= My Awesome Presentation
== Get Ready In...
[%build] * 3 * 2 * 1
== Gather the Crowd
== Shout It Aloud
== Creative Cloud!
[.remark%slice%fit] == This is a Call to All Engineers
THIS IS ACALLTO ALL ENGINEERS
Fanc
y Te
xt
Performance
Why ?
GitHub AsciiDoc
35% faster!
Ecosystem
Source: http://bestgems.org/gems/asciidoctor
GEM
2.5m ASCIIDOCTORJ
0.5m/y ASCIIDOCTOR.JS
35.5k
REPOSITORIES
70CONTRIBUTORS
376SUPPORTERS
80
AsciidoctorJ
AsciidoctorJ
MavenPlugin
GradlePlugin
IntelliJPlugin
JavaDocDoclet
AntPlugin
LeanpubConverter
Inlin
e is
sue
mac
ro# ex. issue:48[] Asciidoctor::Extensions.register do inline_macro :issue do process do |parent, id, attrs| base_uri = parent.document.attr 'uri-issues' create_anchor parent, id, \ type: :link, target: "#{base_uri}/#{id}", attributes: attrs end end end
ruby
Inlin
e is
sue
mac
ro// ex. issue:48[] asciidoctor { extensions { inline_macro (name: 'issue') { parent, id, attrs -> baseUri = parent.document.getAttribute('uri-issues') createInline(parent, 'anchor', id, attrs, [ type: ':link', target: "${baseUri}/${id}".toString(), attributes: attrs ]) } } }
groovy
Asciidoctor.js
Asciidoctor.js
BrowserPreviews
BracketsExtension
GitBookAsciidocFX
AtomPackage
docgist
Inlin
e is
sue
mac
ro# ex. issue:48[] Asciidoctor::Extensions.register do inline_macro :issue do process do |parent, id, attrs| base_uri = parent.document.attr 'uri-issues' create_anchor parent, id, \ type: :link, target: "#{base_uri}/#{id}", attributes: attrs end end end
ruby
Inlin
e is
sue
mac
ro// ex. issue:48[] Opal.Asciidoctor.Extensions.register(function () { this.inlineMacro('issue', function () { this.process((parent, id, attrs) => { const baseUri = parent.getDocument() .getAttribute('uri-issues') return this.createInline(parent, 'anchor', id, { type: 'link', target: `${baseUri}/${id}`, attributes: attrs }) }) }) })
js
Adoption
Future
Semantic versioning
1.5.6 1.5.7 1.6.0 1.7.0 2.0.0
Semantic HTML
https://github.com/jirutka/asciidoctor-html5s
Validation
text
lint :
: inse
cure
-url-
rule
const LinkMacroRx = /(http(s)?:\/\/[^\[]+)\[[\s\S]*?\]/g module.exports = ({ RuleError, report }) => ({ 'ParagraphNode': (node) => { node.children.forEach((line) => { let match while ((match = LinkMacroRx.exec(line.raw)) != null) if (match[2] != null) continue report(line, new RuleError( `Illegal link to a non-secure URL: ${match[1]}`, { index: match.index })) } }) } })
js
$ textlint "**/*.adoc"
server-docs/modules/ROOT/content/user-manual.adoc
14:124 error Illegal link to a non-secure URL: http://example.com (non-secure-url)
✖ 1 problem (1 error, 0 warnings)
Antora
Source 3 Source 5Source 4Source 2Source 1
GIT CLONE / FETCH
Component A Component B Component C Component DComponent D
GRAB FILES FROM SELECT BRANCHES
ASCIIDOC
PAGES
ASSETS
Ant
ora
play
book
site: url: https://docs.example.com title: Docs Site content: sources: - url: https://github.com/acme/solution-docs.git - url: /home/username/projects/server-docs branches: [ v2.5, v3.0, v3.1 ] - url: git@github.com:acme/api-gateway-docs.git branches: v2*
yml
Documentation
http://asciidoctor.org/docs/user-manual/
Antora Asciidoctor
Thank You!asciidoctor.org
A l e x S o t o R e d H a t @ a l e x s o t o b