Creating a documentation site for users with AsciiDoc and Antora
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Number of Parts | 637 | |
| Author | ||
| License | CC Attribution 2.0 Belgium: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor. | |
| Identifiers | 10.5446/52459 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
FOSDEM 2021136 / 637
1
2
7
8
10
11
12
17
29
33
35
38
40
44
48
50
54
59
63
65
85
87
91
95
97
105
108
114
115
119
120
122
126
127
129
130
133
137
140
142
143
147
149
151
156
159
160
161
168
169
170
175
176
177
178
179
182
183
184
187
189
191
193
197
198
204
206
209
212
220
222
224
227
230
233
235
238
242
243
245
247
252
253
255
258
260
261
262
263
264
265
272
273
278
281
282
285
286
287
288
289
294
295
296
302
304
305
308
310
316
320
323
324
328
330
332
335
338
342
343
347
348
349
350
351
360
361
365
368
370
372
374
377
378
380
381
382
383
386
390
392
395
398
402
405
407
408
409
414
419
420
422
425
427
430
439
451
452
453
458
460
461
464
468
470
471
472
473
475
478
485
486
487
491
492
493
495
496
498
509
510
511
512
516
532
534
538
543
548
550
551
554
556
557
559
563
568
570
572
574
575
577
583
585
588
591
593
595
597
601
602
603
604
605
606
607
610
611
617
627
633
634
00:00
WebsitePrincipal idealSoftwareSynchronizationComputer fontComponent-based software engineeringRevision controlAddress spaceData structureModul <Datentyp>Content (media)Repository (publishing)Function (mathematics)Fluid staticsData conversionFormal languageChainLocal GroupFrictionTable (information)Scripting languageJava appletRun time (program lifecycle phase)Open sourceDefault (computer science)Computing platformMarkup languageIntegrated development environmentMaxima and minimaMobile appControl flowElectric currentModule (mathematics)Computer-generated imageryWeb pageFamilyPartial derivativeConsistencyProcess (computing)Structural loadCloningPrice indexServer (computing)Configuration spaceContinuous integrationSoftware developerRootCommon Language InfrastructureInstallation artLocal ringInternetworkingSharewareMathematicsLogarithmEvent horizonSource codeShift operatorDrop (liquid)Computer fileGradientDivisorElement (mathematics)Attribute grammarLink (knot theory)DiagramText editorProbability density functionSelf-organizationRevision controlSoftwareWebsiteWeb pageContent delivery networkContent (media)Source codePlug-in (computing)Electronic mailing listRepository (publishing)Integrated development environmentConfiguration spaceComponent-based software engineeringProjective planeData structureComputer fontServer (computing)Computer filePrincipal idealSubject indexingConsistencyFunction (mathematics)Address spaceModule (mathematics)EmailSharewareData conversionMultiplicationLocal ringInternetworkingFormal languageOpen setMobile appAttribute grammarPartial derivativeDifferent (Kate Ryan album)CloningSpecial unitary groupMultiplication signStructural loadInformation technology consultingTerm (mathematics)Field (computer science)Web-DesignerBenutzerhandbuchMereologyPower (physics)INTEGRALStandard deviationFile formatBitSoftware maintenanceProcess (computing)Branch (computer science)Online helpAuthorizationWeb 2.0Modal logicWorkstation <Musikinstrument>Natural numberWordQuicksortBit rateRight anglePrice indexService (economics)Order (biology)Computer configurationGroup actionEndliche ModelltheorieTheory of relativityProduct (business)Direction (geometry)Virtual machineGame controllerAngleFrictionShared memoryGradientMedical imagingDeterminant1 (number)CAN busGraph coloringSoftware developerNegative numberFrustrationDrum memoryElectric generatorSurgeryCopyright infringementLevel (video gaming)Prime idealSet (mathematics)Maxima and minimaMappingWater vaporComputer animation
08:53
Run time (program lifecycle phase)Android (robot)Partial derivativeDefault (computer science)Installation artIntrusion detection systemRootModul <Datentyp>GradientIntegrated development environmentWeb pageProbability density functionCursor (computers)Cross-site scriptingScripting languageJava appletWeb browserGraphical user interfaceLink (knot theory)Computer-generated imagerySheaf (mathematics)Event horizonRevision controlText editorBuildingGoogolInternetworkingComplete metric spaceGame theoryMiniDiscData structureComputer fontWeb 2.0InformationView (database)Source codeOpen setBookmark (World Wide Web)Computer configurationGroup actionShift operatorKeyboard shortcutCodePlastikkarteComputer fileElectric currentSymbol tableReduction of orderSet (mathematics)Repository (publishing)Component-based software engineeringSpacetimeAttribute grammarLocal ringDisk read-and-write headBranch (computer science)Latent heatModule (mathematics)Expandierender GraphJames Waddell Alexander IIMathematicsLogarithmWebsiteDrop (liquid)Software frameworkOpen sourceFiber bundleContent (media)Gamma functionUniform resource locatorVolumenvisualisierungLambda calculusDiagramExtension (kinesiology)Function (mathematics)Cache (computing)Dean numberElement (mathematics)Alpha (investment)Parameter (computer programming)Server (computing)Hash functionGastropod shellVariable (mathematics)Price indexRobotSoftware developerStandard deviationEmailHyperlinkInformation privacyElectronic mailing listTerm (mathematics)File viewerMoving averageHypertextoutputMathematicsGoodness of fitTorusSheaf (mathematics)Well-formed formulaTelecommunicationNatural numberPurchasingRepository (publishing)Web pageBranch (computer science)Flow separationDifferent (Kate Ryan album)InformationElement (mathematics)Function (mathematics)Arithmetic meanRoundness (object)Point (geometry)Labour Party (Malta)Fiber bundleText editorMedical imagingOrder (biology)Attribute grammarExtension (kinesiology)Projective planeUniform resource locatorBitCodeDigital rights managementPartial derivativeMultiplicationCASE <Informatik>MereologyIntegrated development environmentExecution unitRange (statistics)Metropolitan area networkElectric generatorJava appletIdentity managementMultiplication signGreen's functionImage resolutionLatent heatCellular automaton2 (number)Hazard (2005 film)Asynchronous Transfer ModeData structureData storage deviceMessage passingComplete metric spaceComponent-based software engineeringWater vaporStudent's t-testMetreOpen sourceView (database)QuicksortSet (mathematics)Default (computer science)Scripting languageStandard deviationComputer fileSubject indexingVariable (mathematics)BuildingSource codeIntrusion detection systemMultilaterationDisk read-and-write headLink (knot theory)Electronic program guideEmailValidity (statistics)Local ringRemote procedure callClique-widthTouchscreenProtein foldingWordFormal grammarContent (media)AuthorizationFile formatDiagramSoftware testingFunctional (mathematics)Server (computing)Parameter (computer programming)WebsiteElectronic mailing listPlug-in (computing)Computer fontCursor (computers)Web-DesignerSynchronizationTable (information)BenutzerhandbuchKeyboard shortcutComputer animation
17:39
DivisorView (database)Partial derivativeEvent horizonWeb pageGastropod shellScripting languageFAQElectronic program guideComputing platformContent management systemMarkup languageWeb pagePlug-in (computing)Data structureFrequencyVotingBlogComponent-based software engineeringComputer animationSource code
17:56
Software developerContent (media)Web pageElectric currentWaveIntegrated development environmentWritingControl flowRevision controlPhysical systemElectronic program guideFAQMiniDiscSturm's theoremInformationIntrusion detection systemInternetworkingComputer fileOpen setMenu (computing)Social classShift operatorText editorSpacetimeSymbol tableInformation privacyBookmark (World Wide Web)CollaborationismComponent-based software engineeringPartial derivativeSoftwareSynchronizationLink (knot theory)VideoconferencingExtension (kinesiology)Slide ruleWebsiteDisintegrationAnalytic continuationPlug-in (computing)Computer fontLink (knot theory)Component-based software engineeringWeb pageRevision controlContent (media)Continuous integrationSoftwareWebsiteIntegrated development environmentMultiplication signExtension (kinesiology)DiagramPartial derivativeSynchronizationSlide ruleSurgeryRing (mathematics)Graph coloringConsistencyOnline helpGame controllerSystem callTendonAreaINTEGRALMeasurementQuicksortComputer animation
19:55
Principal idealSystem programmingLocal GroupElement (mathematics)Computer animation
Transcript: English(auto-generated)
00:08
Creating a documentation site for users, with AsciiDoc and Antora. Welcome to my talk at the FOSDEM To The Docs Dev Room. My name is Alexander Schwartz, and I'm a Principal IT Consultant at MSG.
00:22
It's all about empowering your users with documentation, so they get their work done. To do this, you need to keep your documentation content up to date. You need to keep your content consistent. And when you publish new features of your software, you need to publish updated documentation at the same time, in Sun.
00:43
AsciiDoc and Antora help you to do that. Antora provides you with an online documentation site. You can fully automate the process, so you can be up to date all the time. The documentation is searchable and topic-based, so your users can enter a search term in the search field and get a list of all the topics that they can then read.
01:04
You will have a navigation outline that users can browse, and you can have cross-references within your pages to direct users to related content. All your content is grouped by a version and component. Grouping it by version allows you to direct the user to the documentation that matches the version of the software they have installed.
01:26
Grouping it by a component allows you to address different kinds of users with different kinds of content. Antora provides you with the publishing tools and the documentation structure. The documentation is structured into components and modules.
01:42
AsciiDoc will collect content from multiple Git repositories and branches, and will convert all the AsciiDoc content it finds to HTML output. It merges the HTML output with a UI theme and creates a static site. The key benefits are that it has a very fast conversion built on top of Node.js and minimal dependencies.
02:03
It's quite modular and extendable, so you can add the things you need even if they are not part of Antora Core. Antora builds on top of AsciiDoc and AsciiDocdo. AsciiDoc is the language of the content, and AsciiDocdo is the toolchain to create HTML from AsciiDoc content.
02:25
AsciiDoc is frictionless writing using plain text, therefore it's well suited to be checked into Git, so you can also cherry-pick it and compare it with older versions. It has a feature-rich syntax for technical documentation.
02:40
It has great support for lists, for tables, for listings and call-outs, so everything you need to write really good technical documentation. It's been around for more than 15 years and alive and kicking. Last year, the standardization has started at the Eclipse Foundation. AsciiDocdo is the toolchain to create HTML and other output formats from AsciiDoc.
03:03
It's open source, it runs on Java, Ruby and JavaScript runtimes, and it powers Antora's AsciiDoc2 HTML conversion. Today will also be about writing in your IDE. When you write inside your IDE, you will stay focused, as you don't need to switch any apps.
03:22
You will get the best support to collaborate using version control, because IDEs provide great integration with Git. The IntelliJ AsciiDoc plugin provides both Antora and AsciiDoc support. Full disclosure, I'm the current maintainer of this plugin. If you have any questions, please direct them to me,
03:41
either by email or using the GitHub issue tracker. Let's dive into Antora a bit more. Let's start with the structure. As I said, Antora has components. An Antora documentation site can have multiple independent components. Each component is identified by name and version,
04:02
and each component can have multiple modules. And you can have cross references between components and cross references across modules. Each module has a predefined structure. There are pages, images, examples, attachments and partials.
04:20
Partials are content snippets that can be included in multiple places. This helps you to make your site consistent, as you don't need to copy around content. An advanced feature is that a component can be distributed across multiple folders, branches and repositories. When you start small, you might not need this feature. But if you have a bigger documentation project, this comes in very, very helpful.
04:45
Looking at the Antora process, the user just runs Antora and Antora does its job. But what does Antora do? When the user starts Antora, it loads the playbook with a list of all the repositories and branches where the content is.
05:01
Then it clones the skipped repositories. It creates HTML output from all the ASCII.content in there, merges it with the UI theme and the customizations, optionally can also create a search index and other things, and finally creates an output folder with a static site. This static site can be hosted on any web server.
05:22
You can also publish it on a content delivery network or send it as a zip file to your customer. So what are the roles when you set up a new documentation project with Antora? Well, you need to have some authors. They structure and write the content for your documentation site.
05:41
They need to be familiar with Git or willing to learn to work with Git because this is the way you collaborate with other authors. All the content they write, they write in ASCII doc. You would need to have some docuops people who are familiar with automation and infrastructure. They set up a Git repository.
06:01
They write yaml for configuration. They set up a package.json for some version management and set up continuous integration for automation. Last but not least, you need to have some web developers who can create a website. They need to know about HTML and CSS to customize an Antora theme.
06:21
Depending on the amount of customization you want to do, JavaScript will come in helpful. The first steps to set up an Antora site would be that the writers create the first component with a folder structure like this, create an Antora yaml and give the component a name and a version, then create the first page in the pages folder,
06:43
create some navigation entries in a navigation file and reference that in the Antora yaml file. And the docuops people, they will install Antora either using NPM or package.json file. They will create a playbook to generate a local preview site for the authors
07:04
and another playbook to publish the site on the internet. The web developers, they will copy an existing UI theme for Antora or they will create their own and provide the necessary customizations, for example, for the right header and the footer
07:20
so that they have the right content. So now it's demo time. Let's see how this works using the IntelliJ AsciiDoc plugin. The IntelliJ AsciiDoc plugin uses Antora for both the user's guide and the contributor's guide. So this is the IntelliJ AsciiDoc plugin. This Git repository contains both the documentation
07:41
and the source code. I chose to put the documentation in a folder called doc, but you can name it anywhere you like. I open up this folder and see two folders. One is the contributor's guide, one is the user's guide. Each of these is one Antora component. And when I open up the user's guide, you see the typical structure of a component.
08:01
I see the Antora yaml file and a folder called modules with all the modules in this component. I open up this component and see the mandatory elements in here. That's the name of the component and the version of the component. I can specify additional optional attributes here, being like the title,
08:21
or I could mark it as a pre-release. I can define the start page. Now I open up the modules folder and see that there is a navigation file in here. Once I open up this navigation file, I see a list of navigation items. They are on different levels, with the usual askadoc syntax.
08:41
What I reference here on the left in the source code is only the name of the file. On the right, I see then the navigation title. I click on the installation adoc and now I'm in the installation file. I see the title here. That's also part of the navigation. I see my sections here,
09:00
but they have IDs that I can reference later. There's a preview. I can scroll them independently, but once I've placed my cursor, preview scrolls to the location of the cursor. Here I have a partial that's being included here, a partial, a common snippet of text describing the Java FX preview
09:21
that I use in multiple places, and I can include it like this. I can reference other pages using xref, or I can use local references within this page like this. The text editor of the askadoc source behaves like any other text editor in an IDE.
09:43
You can fold sections. You can navigate to references. You have auto-completion, so if I want to add a reference here, I will get an auto-completion of all IDs that are within range.
10:00
This behaves really like code. Auto-completions and validations you can mark to-dos will then appear in the to-do list, so all the convenience elements you would expect from an IDE are here. I can also choose the structure outline view, so the same structure that I see here and that I can fold.
10:21
I can get myself an overview about this section by expanding and drilling down through the sections of this document, and use it to navigate within the source code. So it's a full-featured editor, as you would expect. This editor also contains word checking
10:41
and grammar checking, so we are now looking here at the keymap. The keymap shows the use of tables in askadoc, so I define the width of the different columns, the kind of grid I want to show here, formatted content within a cell with keyboard macros, and once I switch to the preview,
11:01
so there's both a side-by-side preview, since I have a reduced screen resolution for this demo, I switch to a preview-only mode, and the author can proofread it and see that the formatings are all correct. As an author, when I check out different components in different branches and repositories,
11:21
I can use all functionality of the IDE, and I can get a good preview of the content, the navigation, and the relevant cross-references. Having both the docs and the code in one Git repository helps me to keep them both in sync. When I, for example, look at the history of this Git repository and search for a specific issue,
11:43
in this case 5.5.6, and have a look what kind of changes were committed for this one issue, I see that there are some documentation changes here regarding a style sheet, there's a documentation change for the changelog, there are code changes, and there are test changes. This makes it straightforward to do code reviews
12:03
and make it as you can check it from your list. There has been a code change, there has been a test change, the documentation has been updated, and a changelog as well. Everything looks fine. Let's look at the second repository. The second repository contains the playbooks for Intora and shows what a docuops person does
12:23
to automate a build for the documentation. So this is now the repository for the website. Looking at this, there are several files and folders related to Intora. One is the Intora playbook that publishes the information on the final site. Looking at this file, you see there's a title for the site,
12:43
there's a URL where the docs will be accessible, there's a start page, so I set it to the index adoc file in the user's guide, that should be the start page for the documentation, and I point it to the Git repository where it finds the documentation that it should render.
13:00
There's a URL for the Git repository, and there are two start paths for the two components we've seen earlier, plus the branch where I should look for it. So this defines where the content is, and now there's a section about the UI. There's a URL with a zip file with all the default UI elements that I'm about to use,
13:21
plus a folder with a supplemental UI where I overwrite some of the files in the standard UI bundle. And the final output will be created in a folder called site slash docs. Below I can also define extensions and attributes that should be global to this site. In this playbook for the final site,
13:41
I define where to fetch the sources from, from a remote location, but when I want to render a preview locally, there's a little bit customized author's playbook. When I open this file, they look very, very similar, but this file picks the sources not from a remote Git location, but from a local Git location that's relative to this file.
14:02
So this assumes that an author who wants to render a preview checks out this Git repository just next to the ascii-doctor-intelliJ plugin Git repository. There is the same start path with a difference. In the previous playbook, I had this branches point to the master branch. This one points to head,
14:21
meaning this should be the currently checked out sandbox of the other Git repository. So this playbook will render the contents of this Git repository, even if they're not yet checked into that Git repository. This makes it very handy to render a local preview. All the other elements are basically the same like before.
14:42
To set up Antora, I prefer setting up a package.json file that allows me to specify all depth dependencies for Antora and all the extensions that I am about to use here. So this antora-lunar is, for example, the search index that I'm using on this site. I see Dr. Crokey allows me to render diagrams within my documentation.
15:02
Up here in the section scripts, there's a predefined script for the author's playbook and the site's playbook with all the necessary parameters that I wanted to have in here. There's also a command in here to start up a small local HTTP server to get a real good preview of the rendered site.
15:23
These commands are later called from a build script. I chose bash to write this in this case. This will first run Jekyll for the start page. We'll then set some environment variables and finally use yarn to run the build. So this full build script
15:40
that includes both building a start page using Jekyll and Antora runs on Netlify and on for about two minutes and after that two minutes the site is live. After we now looked at the roles of the writer and the docuops person, we now look at the role of the web developer and the web developer is customizing
16:02
the UI theme of Antora. What do they need to do? The UI bundle contains all the default files for, for example, CSS, for images, for JavaScript and layouts and partials and a minimal setup if you're using the standard Antora UI
16:21
would be to overwrite the partials for footer content and header content. So, for example, if I compare the footer content, you see here on the left there was a text this page was built using the Antora default UI. So this has now changed so that it matches this documentation repository. It lists the contributors.
16:42
It updates the relevant links. This is all the minimal change you want to do at least for the footer and the head would be similar. Looking at the head content, old and new, you see that there were original navigation items where I added a logo in here.
17:00
I also added a doc search snippet in here and usually you want to have navigation items that are then project specific. So I decided to link the quick start guide and the contributors guide and users guides in here. These are the two snippets that you want to overwrite when you set up a new project.
17:22
I added some more customizations as you see here. I added a lightbox element. I updated the scroll bar to match my project. So this is the way you add customizations to the Antora UI. Looking at the resulting page, so this is the web page
17:41
for the IntelliJ AsciiDoc plugin. The start page has been created using Jekyll as it gives me more flexibility to create this page compared to the very, very structured Antora layout where I now choose the users guide here. This is the Antora component for the users guide with its outline on the left.
18:02
There's a link to edit this page with an outline of the current page. We've looked at the plugin installation before. This is the text as it appears on this page here. If I choose features keymap, you see also the keymap
18:22
like it appeared also in the IDE. And if I scroll to the very end, we see down here the footer as I updated it. So this is the end of the tour. Let's go back to the slides for a summary. It's all about empowering the users with documentation
18:42
so they get their work done. AsciiDoc and Antora help you here. They help you to keep your content up to date as you can collaborate as a team using version control. They help you to keep your content consistent so each component version measures a software version and you can do all the deduplication of content
19:03
for example using partials that you need to provide a really consistent experience for your users reading your documentation. And Antora provides you with the tools that when you publish new features for your software that you can publish documentation for these new features at the same time in sync using continuous integration and continuous delivery
19:22
and fully automated. These are the links for all the tools available today. It's AsciiDoc to provide the content. It's Antora to create a documentation site. It's the IntelliJ AsciiDoc plugin to have a fully integrated experience inside your IDE.
19:40
For those who want to integrate diagrams into their documentation, there's for example planned URL. And if you want to integrate those into your documentation site, have a look at the AsciiDoc Quarkie extension that also supports Antora. Thank you very much for your attention and looking forward to your questions.