├── asciidoc-markup-sample-doc
├── .gitignore
├── README.md
├── docinfo.html
├── image.png
└── asciidoc-markup-samples.adoc
├── README.md
└── .travis.yml
/asciidoc-markup-sample-doc/.gitignore:
--------------------------------------------------------------------------------
1 | asciidoc-markup-samples.html
2 |
--------------------------------------------------------------------------------
/asciidoc-markup-sample-doc/README.md:
--------------------------------------------------------------------------------
1 | The sample document for the Red Hat AsciiDoc Conventions.
2 |
--------------------------------------------------------------------------------
/asciidoc-markup-sample-doc/docinfo.html:
--------------------------------------------------------------------------------
1 |
4 |
--------------------------------------------------------------------------------
/asciidoc-markup-sample-doc/image.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/redhat-documentation/asciidoc-markup-conventions/HEAD/asciidoc-markup-sample-doc/image.png
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Red Hat Documentation Asciidoc Mark-up Conventions
2 |
3 | The Asciidoc-markup-conventions initiative tries to identify the best practises and styles for the Asciidoc Mark-up that is to be used in Red Hat documents. The matter was discussed heavily across all Red Hat documentation teams to reach an agreement on marking up various elements used in the documentation.
4 |
5 | Finally, we have come up with a quick reference of the AsciiDoc markup. You can find the latest results at https://redhat-documentation.github.io/asciidoc-markup-conventions. Build status: [](https://travis-ci.org/redhat-documentation/asciidoc-markup-conventions)
6 |
7 |
--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | sudo: required
2 |
3 | branches:
4 | only:
5 | - master
6 |
7 | services:
8 | - docker
9 |
10 | before_install:
11 | - mkdir -p output
12 | - docker pull asciidoctor/docker-asciidoctor
13 |
14 | script:
15 | - docker run -v $TRAVIS_BUILD_DIR:/documents/ --name asciidoc-to-html asciidoctor/docker-asciidoctor asciidoctor --destination-dir=/documents/output --out-file=index.html asciidoc-markup-sample-doc/asciidoc-markup-samples.adoc
16 |
17 | after_error:
18 | - docker logs asciidoc-to-html
19 |
20 | after_failure:
21 | - docker logs asciidoc-to-html
22 |
23 | deploy:
24 | provider: pages
25 | skip_cleanup: true
26 | github_token: $GH_TOKEN # Set in travis-ci.com dashboard
27 | local_dir: output
28 | on:
29 | branch: master
30 |
--------------------------------------------------------------------------------
/asciidoc-markup-sample-doc/asciidoc-markup-samples.adoc:
--------------------------------------------------------------------------------
1 | :experimental:
2 | :source-highlighter: prettify
3 | :docinfo1:
4 |
5 | = AsciiDoc Mark-up Quick Reference for Red{nbsp}Hat Documentation
6 |
7 | == AsciiDoc markup elements used in Red{nbsp}Hat documentation
8 |
9 | [NOTE]
10 | ====
11 | Some markup examples used in this overview are based on new Asciidoctor features and they are not a part of the standard set of elements. Please, use the `:experimental:` tag in the header of your document to enable this functionality.
12 | ====
13 |
14 | [cols="3,4,4"]
15 | |===
16 | |Element|Mark-up|Example rendered output
17 |
18 | a|Anchor
19 |
20 | NOTE: The `+++{context}+++` variable is recommended for making modules reusable. Example: `+++[id="section-header_{context}"]+++`. For details, see the link:https://redhat-documentation.github.io/modular-docs/#reusing-modules[Modular Documentation Reference Guide].
21 |
22 | a|
23 | ....
24 | [id="section-header_{variable}"]
25 | Section Header
26 | ....
27 | a|
28 | *Section Header*
29 |
30 | |Application name
31 | a|No special markup
32 | a| The foo application.
33 |
34 | |Code blocks
35 | a|
36 | ....
37 | [source,java]
38 | ----
39 | public class HelloWorld {
40 | public static void main(String[] args) {
41 | System.out.println("Hello, World");
42 | }
43 | }
44 | ----
45 | ....
46 |
47 | a|
48 | [source,java]
49 | ----
50 | public class HelloWorld {
51 | public static void main(String[] args) {
52 | System.out.println("Hello, World");
53 | }
54 | }
55 | ----
56 |
57 | |Code - inline
58 | a|
59 | ....
60 | `print("Hello, World!")`
61 | ....
62 |
63 | a| `print("Hello, World!")`
64 |
65 | |Command block
66 | a|
67 | ....
68 | ----
69 | $ echo "Hello, World!" > hello.txt
70 | ----
71 | ....
72 | a|
73 | ----
74 | $ echo "Hello, World!" > hello.txt
75 | ----
76 |
77 | |Command - inline
78 | a|
79 | ....
80 | Use the [command]`oc get` command to get a list of services.
81 | ....
82 |
83 | a|Use the [command]`oc get` command to get a list of services.
84 |
85 | |Emphasis for a term
86 | a|
87 | ....
88 | In this release, the terms _worker machine_ and _compute machine_ are used interchangeably.
89 | ....
90 |
91 | a|In this release, the terms _worker machine_ and _compute machine_ are used interchangeably.
92 |
93 | |Filenames or directory paths
94 |
95 | a|
96 | ....
97 | Edit the [filename]`kubeconfig` file as required and save your changes.
98 |
99 | The [filename]`express.conf` configuration file is located in the [filename]`/usr/share/` directory.
100 | ....
101 |
102 | a|Edit the [filename]`kubeconfig` file as required and save your changes.
103 |
104 | The [filename]`express.conf` configuration file is located in the [filename]`/usr/share/` directory.
105 |
106 | |GUI Text
107 |
108 | a|
109 | ....
110 | The web browser displays *404* for an unreachable URL.
111 | ....
112 |
113 | a|The web browser displays *404* for an unreachable URL.
114 |
115 | |GUI Button
116 | a|
117 | ....
118 | Click btn:[Save As] to save the file under a different name.
119 | ....
120 |
121 | a|Click btn:[Save As] to save the file under a different name.
122 |
123 | |GUI Menu
124 |
125 | a|
126 | ....
127 | Navigate to menu:File[Import>Import csv] to import a csv file.
128 | ....
129 |
130 | a|Navigate to menu:File[Import>Import csv] to import a csv file.
131 |
132 | |Inline Image
133 |
134 | a|
135 | ....
136 | image::image.png[width=25px]
137 | ....
138 |
139 | a| image::image.png[width=25px]
140 |
141 | | Block Image
142 | a|
143 | ....
144 | .Tux
145 | image::image.png[width=100px]
146 | ....
147 | a| .Tux
148 | image::image.png[width=100px]
149 |
150 |
151 | |Inline operations and user input
152 |
153 | a|
154 | ....
155 | The `GET` operation can be used to do something.
156 |
157 | Answer by typing `Yes` or `No` when prompted.
158 | ....
159 |
160 | a|The `GET` operation can be used to do something.
161 |
162 | Answer by typing `Yes` or `No` when prompted.
163 |
164 | | Keyboard shortcuts
165 | a|
166 | ....
167 | kbd:[Ctrl+Alt+Del]
168 | ....
169 | a| kbd:[Ctrl+Alt+Del]
170 |
171 | | Link (external)
172 |
173 | a|
174 | ....
175 | link:http://www.redhat.com[Red Hat]
176 | ....
177 |
178 | a| link:http://www.redhat.com[Red Hat]
179 |
180 |
181 | a|Lists
182 |
183 | NOTE: Do not put steps in bold.
184 |
185 | a|
186 |
187 | ....
188 | .Ordered list
189 |
190 | . First item
191 | . Second item
192 | . Third item
193 |
194 | .Unordered list
195 |
196 | * This
197 | * That
198 | * The other
199 |
200 | .Definition or labeled list
201 |
202 | Term A:: description
203 | Term B:: description
204 | ....
205 |
206 | a|.Ordered list
207 |
208 | . First item
209 | . Second item
210 | . Third item
211 |
212 | .Unordered list
213 |
214 | * This
215 | * That
216 | * The other
217 |
218 | .Definition or labeled list
219 |
220 | Term A:: description
221 | Term B:: description
222 |
223 | |Literal value
224 |
225 | a|
226 | ....
227 | The function returns `true`.
228 | ....
229 |
230 | a|The function returns `true`.
231 |
232 |
233 | |Package
234 | a|
235 | ....
236 | Install the [package]`iscsi-initiators-utils` package.
237 | ....
238 |
239 | a|Install the [package]`iscsi-initiators-utils` package.
240 |
241 | |Product name
242 | a|No special markup. Use +++{nbsp}+++ in the company and product names. Example: Red+++{nbsp}+++Hat JBoss+++{nbsp}+++Data+++{nbsp}+++Grid
243 | a|Red{nbsp}Hat JBoss{nbsp}Data{nbsp}Grid
244 |
245 | |Reference to Red Hat guides
246 | a|
247 | ....
248 | For more information, see the JBoss EAP link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.2/html/getting_started_guide/index[_Getting Started Guide_].
249 | ....
250 |
251 | a|For more information, see the JBoss EAP link:https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.2/html/getting_started_guide/index[_Getting Started Guide_].
252 |
253 | |System or software variable to be replaced by the user
254 | a|
255 | ....
256 | Use the following command to roll back a deployment, specifying the deployment name: `oc rollback __`.
257 | ....
258 |
259 | a|
260 | Use the following command to roll back a deployment, specifying the deployment name: `oc rollback __`.
261 |
262 |
263 | |System or software configuration parameter or environment variable
264 | a|
265 | ....
266 | Use the `_IP_ADDRESS_` environment variable for the server IP address.
267 | ....
268 |
269 | a|Use the `_IP_ADDRESS_` environment variable for the server IP address.
270 |
271 | |System item, daemon, or service
272 |
273 | a|
274 | ....
275 | Include the `libfreetype` library.
276 |
277 | Stop the `NetworkManager` daemon.
278 |
279 | Start the `mysql` service.
280 | ....
281 |
282 | a|Include the `libfreetype` library.
283 |
284 | Stop the `NetworkManager` daemon.
285 |
286 | Start the `mysql` service.
287 |
288 | |===
289 |
290 |
291 | == Additional resources
292 |
293 | . link:http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual].
294 | . link:http://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoctor Writer's Guide].
295 | . link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference].
296 |
--------------------------------------------------------------------------------