📄 How to use Asciidoctor to format the document like a specification

!README-asciidoctor-requirement.md

📄 How to use Asciidoctor to format the document like a specification

• Gist page
• Output PDF file
• 日本語版 / Japanese version

About this article

This article describes how to use Asciidoctor to format the document like a specification

Workflow

The workflow is as follows:

1. Installing Asciidoctor
2. Preparing for coding
3. Coding
4. Generating a HTML file
5. Operation check

Installing Asciidoctor

Instructions for installing Asciidoctor are detailed in the [Asciidoctor Installation section] (https://asciidoctor.org/#installation). For macOS, you can install it with the following command.

brew install asciidoctor

Preparing for coding

Run the following command in the terminal to prepare for coding.

mkdir asciidoctor-requirement
cd asciidoctor-requirement
touch requirement.adoc
touch style.css

Coding

requirement.adoc

Open requirement.adoc in the editor and enter the following content.

Click to go to requirement.adoc.txt

style.css

Open style.css in the editor and enter the following content.

Click to go to style.css

Generating a HTML file

Run the following command in the terminal to generate a HTML file.

asciidoctor -a stylesheet=style.css -o dist/requirement.html requirement.adoc

Operation check

Open the generated HTML file. If you use macOS, the following command is useful.

open dist/requirement.html

PDF output is also possible by using the print function of the browser. Firefox is recommended because it has a function to display the page number and the total number of pages in the footer.

Conclusion

I find it convenient that Asciidoctor can make detailed settings, such as putting numbers and captions in figures and tables. While simple Markdown is suitable for writing blog articles, the Asciidoctor is suitable for writing documents.

I wrote another article titled How to take screenshots with Puppeteer. The method described in that article is useful for automating screenshots, such as when you want to include a screen example in a requirements definition document. If you are interested, please read it as well.

I hope this article can help those who are tired of writing specs in Word. Thank you for reading!

.gitignore

/dist/

makefile

build:
	asciidoctor \
		-a stylesheet=style.css \
		-o dist/requirement.html \
		requirement.adoc.txt

requirement.adoc.txt

:table-caption: Table
:figure-caption: Figure

= Requirements definition of Tech Blog System - Version 1.0 - 2022-04-21

[.cover-project]
Tech Blog System:

[.cover-document]
Requirements Definition

[.cover-version]
Version 1.0

[.cover-date]
April 21st, 2022

[.cover-company]
Lorem Ipsum Co. Ltd.

[.cover-address]
4-3934, Sekihara minami, Nagaoka city, Niigata prefecture, Japan.

[.cover-tel]
TEL: +81-258-94-5233

[.cover-email]
E-mail: [email protected]



== Purpose and structure

The purpose of this document is to build consensus between the outsourcer and the outsourcee of this system development by defining the functional requirements of the system. The structure of this document is shown below.

. Purpose and structure
. List of pages
. Page layout
. Top page
. Article list page
. Article detail page
. Revision history



== List of pages

. Article list page
. Article detail Page



== Page layout

=== Content

. Header
.. Logo link
. Breadcrumb
. Main content
. Footer
.. Copyright

=== Behavior

. When the user clicks the logo link, the system displays the top page.



== Article list page

=== Content

. Main content
.. List navigation
... Article links
.... Posted date
.... Title

=== Behavior

. When the user clicks an article link, the system displays the article detail page.


== Article detail page

=== Content

. Main content
.. Menu
... Back link
.. Title
.. Posted date
.. Text
.. Related posts navigation
... Article links
.... Posted date
.... Title

=== Behavior

. When the user clicks the back link, the system displays the article list page.
. When the user clicks an article link, the system displays the article detail page.



== Revision history

The revision history of this document is shown in the table below.

.Revision history
[cols="1,3,3,2"]
|===
| Version | Date | Comment | Author

| 1.0 | April 21st, 2022 | The first edition | T. Susukida
|===

requirement.pdf

style.css

@page {
  margin: 20mm 20mm 20mm 20mm;
}

* {
  box-sizing: border-box;
}

html {
  font-family: "Hiragino Mincho ProN";
  font-size: 12pt;
  text-align: justify;
}

@media screen {
  body {
    background: #eeeeee;
  }
}

#header {
  display: none;
}

#footer {
  display: none;
}

.sect1 {
  page-break-before: always;
}

@media screen {
  .sect1, #preamble {
    width: 210mm;
    min-height: 297mm;
    background: #ffffff;
    margin-left: auto;
    margin-right: auto;
    padding: 20mm;
    margin-bottom: 10mm;
  }
}

@media screen {
  #preamble {
    width: 210mm;
    min-height: 297mm;
    background: #ffffff;
    margin-left: auto;
    margin-right: auto;
    padding: 20mm;
    margin-bottom: 10mm;
  }
}

h2 {
  font-weight: normal;
  border-bottom: 1pt solid black;
  font-size: 18pt;
  margin: 0;
  margin-bottom: 1rem;
}

h3 {
  font-weight: normal;
  font-size: 14pt;
  margin: 0;
  margin-bottom: 1rem;
}

h4 {
  font-weight: normal;
  font-size: 12pt;
  margin: 0;
  margin-bottom: 1rem;
}

p {
  margin: 0;
  margin-bottom: 1rem;
  padding: 0;
}

.olist ol {
  list-style: none;
  margin: 0;
  margin-left: 1rem;
  padding: 0;
}

.olist p {
  display: inline;
}

ol.arabic {
  counter-reset: ol1;
  margin-left: 0;
  margin-bottom: 1rem;
  border: 1pt solid black;
  padding: 1rem;
}

ol.arabic > li {
  counter-increment: ol1;
}

ol.arabic > li:before {
  content: "(" counter(ol1) ")";
}

ol.loweralpha {
  counter-reset: ol2;
}

ol.loweralpha > li {
  counter-increment: ol2;
}

ol.loweralpha > li:before {
  content: "(" counter(ol1) "." counter(ol2) ")";
}

ol.lowerroman {
  counter-reset: ol3;
}

ol.lowerroman > li {
  counter-increment: ol3;
}

ol.lowerroman > li:before {
  content: "(" counter(ol1) "." counter(ol2) "." counter(ol3) ")";
}

ol.upperalpha {
  counter-reset: ol4;
}

ol.upperalpha > li {
  counter-increment: ol4;
}

ol.upperalpha > li:before {
  content: "(" counter(ol1) "." counter(ol2) "." counter(ol3) "." counter(ol4) ")";
}

ol.upperroman {
  counter-reset: ol5;
}

ol.upperroman > li {
  counter-increment: ol5;
}

ol.upperroman > li:before {
  content: "(" counter(ol1) "." counter(ol2) "." counter(ol3) "." counter(ol4) "." counter(ol5) ")";
}

img {
  width: 100%;
  border: 1pt solid black;
}

.imageblock {
  text-align: center;
}

.imageblock .title {
  margin-bottom: 1rem;
}

table {
  width: 100%;
  border-collapse: collapse;
}

th {
  border: 1pt solid black;
  border-bottom: 3pt double black;
  text-align: left;
  font-weight: normal;
  padding: 0.25rem;
}

td {
  border: 1pt solid black;
  padding: 0.25rem;
}

td p {
  margin: 0;
  padding: 0;
}

pre {
  border: 1pt solid black;
  padding: 1rem;
}

code {
  font-family: "Hiragino Mincho ProN";
}

body {
  counter-reset: h2;
}

h2 {
  counter-increment: h2;
  counter-reset: h3;
}

h2:before {
  content: counter(h2) ". ";
}

h3 {
  counter-increment: h3;
  counter-reset: h4;
}

h3:before {
  content: counter(h2) "." counter(h3) ". ";
}

h4 {
  counter-increment: h4;
}

h4:before {
  content: counter(h2) "." counter(h3) "." counter(h4) ". ";
}

.cover-project p {
  margin-top: 60mm;
  text-align: center;
  font-size: 24pt;
  border-top: 1mm solid black;
  margin-bottom: 0;
  padding-top: 5mm;
}

.cover-document p {
  text-align: center;
  font-size: 24pt;
  border-bottom: 1mm solid black;
  padding-bottom: 5mm;
}

.cover-version p {
  text-align: center;
  font-size: 12pt;
  padding-top: 1rem;
}

.cover-date p {
  text-align: center;
  font-size: 12pt;
}

.cover-company p {
  text-align: center;
  font-size: 18pt;
  margin-top: 50mm;
}

.cover-address p {
  text-align: center;
  font-size: 12pt;
  padding-top: 1rem;
}

.cover-tel p {
  text-align: center;
  font-size: 12pt;
  margin-bottom: 0;
}

.cover-email p {
  text-align: center;
  font-size: 12pt;
}

.cover-email a {
  color: black;
  text-decoration: none;
}