document-attributes-reference.adoc 27.5 KB
Newer Older
1
= Document Attributes Reference
2
// TODO use icons or emoji for y and n
3
4
:y: Yes
:n: No
5
:endash: –
6
:url-epoch: https://reproducible-builds.org/specs/source-date-epoch/
7

8
9
Document attributes are used either to configure behavior in the processor or to relay information about the document and its environment.
This page catalogs all the built-in (i.e., reserved) document attributes in AsciiDoc.
10

11
Unless otherwise marked, these attributes can be modified (set or unset) from the API using the `:attributes` option, from the CLI using the `-a` option, or in the document (often in the document header) using an attribute entry.
12

13
Use the follow legend to understand the columns and values in the tables on this page.
14

15
16
17
[horizontal]
Set By Default:: The attribute is automatically set and assigned a default value by the AsciiDoc processor.
The default value is indicated in *bold* (e.g., `*skip*`).
18

19
20
Allowable Values:: Allowable values for the attribute.
Numeric values and values shown in _italic_ are instructional and indicate a value type (e.g., _any_, _empty_, _number_, 1{endash}5, etc.).
21
+
22
23
* _any_ -- Any value is accepted.
* _empty_ -- Indicates the attribute doesn't require an explicit value.
24
The attribute is simply turned on by being set.
25
26
* _empty_[=`effective`] -- In some cases, an empty value is interpreted by the processor as one of the allowable non-empty values.
This effective value is prefixed with an equals sign and enclosed in square brackets (e.g., [=`auto`]).
27
An attribute reference will resolve to an empty value rather than the effective value.
28
29
* (`implied`) -- Built-in attributes that are not set may have an implied value.
The implied value is enclosed in parentheses (e.g., (`attributes`)).
30
An implied value can't be resolved using an attribute reference.
31

32
33
+
If the attribute doesn't accept _any_ or _empty_, than you must only assign one of the allowable values or specified value type.
34

35
36
37
38
Header Only:: The attribute must be set or unset by the end of the document header (i.e., set by the API, CLI, or in the document header).
Otherwise, the assignment won't have any effect on the document.
If an attribute is not marked as _Header Only_, it can be set anywhere in the document, assuming the attribute is not locked by the API or CLI.
However, changing an attribute only affects behavior for content that follows the assignment (in document order).
39

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
== Intrinsic attributes

Intrinsic attributes are set automatically by the processor.
These attributes provide information about the document being processed (e.g., `docfile`), the security mode under which the processor is running (e.g., `safe-mode-name`), and information about the user's environment (e.g., `user-home`).

Many of these attributes are read only, which means they can't be modified (with some exceptions).
Attributes which are not are marked as modifiable.
Attributes marked as both modifiable and API/CLI Only can only be set from the API or CLI.
All other attributes marked as modifiable must be set by the end of the header (i.e., Header Only).

[cols="30m,20,^10,^10,30"]
|===
.>|Name .>|Allowable Values .>|Modifiable .>|API/CLI Only .>|Notes

|backend
|_any_ +
_ex._ html5
|{y}
|{n}
|The backend used to select and activate the converter that creates the output file.
Usually named according to the output format (e.g., `html5`)

|basebackend
|_any_ +
_ex._ html
|{n}
|n/a
|The generic backend on which the backend is based.
Typically derived from the backend value minus trailing numbers (e.g., the basebackend for `docbook5` is `docbook`).
May also indicate the internal backend employed by the converter (e.g., the basebackend for `pdf` is `html`).

|docdate
|_date (ISO)_ +
_ex._ 2019-01-04
|{y}
|{n}
|Last modified date of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^

|docdatetime
|_datetime (ISO)_ +
_ex._ 2019-01-04 19:26:06 UTC
|{y}
|{n}
|Last modified date and time of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^

|docdir
|_directory path_ +
_ex._ /home/user/docs
|If input is a string
|{y}
|Full path of the directory that contains the source document.
Empty if the safe mode is SERVER or SECURE (to conceal the file's location).

|docfile
|_file path_ +
_ex._ /home/user/docs/userguide.adoc
|If input is a string
|{y}
|Full path of the source document.
Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file's location).

|docfilesuffix
|_file extension_ +
_ex._ .adoc
|If input is a string
|{y}
|File extension of the source document, including the leading period.

|docname
|_file stem basename_ +
_ex._ userguide
|If input is a string
|{y}
|Root name of the source document (no leading path or file extension).

|doctime
|_time (ISO)_ +
_ex._ 19:26:06 UTC
|{y}
|{n}
|Last modified time of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^

|docyear
|_integer_ +
_ex._ {docyear}
|{y}
|{n}
|Year that the document was last modified.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^

|embedded
|_empty_
|{n}
|n/a
|Only set if content is being converted to an embedded document (i.e., body of document only).

|filetype
|_any_ +
_ex._ html
|If input is a string
|{y}
|File extension of the output file name (without leading period).

|htmlsyntax
|`html` +
`xml`
|{n}
|n/a
|Syntax used when generating the HTML output.
Controlled by and derived from the backend name (html=html or xhtml=html).

|localdate
|_date (ISO)_ +
_ex._ 2019-02-17
|{y}
|{n}
|Date when the document was converted.^[<<note-sourcedateepoch,2>>]^

|localdatetime
|_datetime (ISO)_ +
_ex._ 2019-02-17 19:31:05 UTC
|{y}
|{n}
|Date and time when the document was converted.^[<<note-sourcedateepoch,2>>]^

|localtime
|_time (ISO)_ +
_ex._ 19:31:05 UTC
|{y}
|{n}
|Time when the document was converted.^[<<note-sourcedateepoch,2>>]^

|localyear
|_integer_ +
_ex._ {localyear}
|{y}
|{n}
|Year when the document was converted.^[<<note-sourcedateepoch,2>>]^

|outdir
|_directory path_ +
_ex._ /home/user/docs/dist
|{n}
|n/a
|Full path of the output directory.
(Cannot be referenced in the content.
Only available to the API once the document is converted).

|outfile
|_file path_ +
_ex._ /home/user/docs/dist/userguide.html
|{n}
|n/a
|Full path of the output file.
(Cannot be referenced in the content.
Only available to the API once the document is converted).

|outfilesuffix
|_file extension_ +
_ex._ .html
|{y}
|{n}
|File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.).

|safe-mode-level
|`0` +
`1` +
`10` +
`20`
|{n}
|n/a
|Numeric value of the safe mode setting.
(0=UNSAFE, 1=SAFE, 10=SERVER, 20=SECURE).

|safe-mode-name
|`UNSAFE` +
`SAFE` +
`SERVER` +
`SECURE`
|{n}
|n/a
|Textual value of the safe mode setting.

|safe-mode-unsafe
|_empty_
|{n}
|n/a
|Set if the safe mode is UNSAFE.

|safe-mode-safe
|_empty_
|{n}
|n/a
|Set if the safe mode is SAFE.

|safe-mode-server
|_empty_
|{n}
|n/a
|Set if the safe mode is SERVER.

|safe-mode-secure
|_empty_
|{n}
|n/a
|Set if the safe mode is SECURE.

|user-home
|_directory path_ +
_ex._ /home/user
|{n}
|n/a
|Full path of the home directory for the current user.
Masked as `.` if the safe mode is SERVER or SECURE.
|===
[[note-docdatetime]]^[1]^ Only reflects the last modified time of the source document file.
It does not consider the last modified time of files which are included.

[[note-sourcedateepoch]]^[2]^ If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable.
This override offers one way to make the conversion reproducible.
See the {url-epoch}[source date epoch specification] for more information about the SOURCE_DATE_EPOCH environment variable.
Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., `-0600`) or UTC if the time zone offset is 0).
To force the use of UTC, set the `TZ=UTC` environment variable when invoking Asciidoctor.

263
264
== Compliance attributes

265
[cols="30m,20,^10,^10,30"]
266
|===
267
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
268
269

|attribute-missing
270
|`drop` +
271
`drop-line` +
272
`*skip*` +
273
274
`warn`
|{y}
275
|{n}
276
277
278
|Controls how xref:unresolved-references.adoc#missing[missing attribute references] are handled.

|attribute-undefined
279
280
|`drop` +
`*drop-line*`
281
|{y}
282
283
|{n}
|Controls how xref:unresolved-references.adoc#undefined[attribute unassignments] are handled.
284
285

|compat-mode
286
|_empty_
287
|{n}
288
289
|{n}
|Controls when the legacy parsing mode is used to parse the document.
290
291

|experimental
292
|_empty_
293
294
|{n}
|{y}
295
|Enables xref:macros:ui-macros.adoc[] and the xref:macros:keyboard-macro.adoc[].
296
297

|reproducible
298
|_empty_
299
300
301
302
303
|{n}
|{y}
|Prevents last-updated date from being added to HTML footer or DocBook info element.
Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document.
//Alternatively, you can use the SOURCE_DATE_EPOCH environment variable to fix the value.
304
305
306
307
308
309
310

|skip-front-matter
|_empty_
|{n}
|{y}
|Consume YAML-style frontmatter at top of document and store it in `front-matter` attribute.
//<<front-matter-added-for-static-site-generators>>
311
312
313
|===

[#builtin-attributes-i18n]
314
== Localization and numbering attributes
315

316
[cols="30m,20,^10,^10,30"]
317
|===
318
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
319
320

|appendix-caption
321
322
|_any_ +
`*Appendix*`
323
|{y}
324
|{n}
325
326
327
|Label added before an xref:sections:appendix.adoc[appendix title].

|appendix-number
328
329
330
331
|_character_ +
(`@`)
|{n}
|{n}
332
|Sets the seed value for the appendix number sequence.^[<<note-number,1>>]^
333
334

|appendix-refsig
335
336
|_any_ +
`*Appendix*`
337
|{y}
338
|{n}
339
340
341
|Signifier added to Appendix title cross references.

|caution-caption
342
343
|_any_ +
`*Caution*`
344
|{y}
345
|{n}
346
347
348
|Text used to label CAUTION admonitions when icons aren't enabled.

|chapter-number
349
|_number_ +
350
(`0`)
351
352
|{n}
|{n}
353
|Sets the seed value for the chapter number sequence.^[<<note-number,1>>]^
354
_Book doctype only_.
355
356

|chapter-refsig
357
358
|_any_ +
`*Chapter*`
359
|{y}
360
|{n}
361
|Signifier added to Chapter titles in cross references.
362
_Book doctype only_.
363

364
365
366
367
|chapter-signifier
|_any_
|{n}
|{n}
368
369
370
371
|xref:sections:chapters.adoc[Label added to level-1 section titles (chapters)].
_Book doctype only_.

|example-caption
372
373
|_any_ +
`*Example*`
374
|{y}
375
|{n}
376
377
378
|Text used to label example blocks.

|example-number
379
|_number_ +
380
(`0`)
381
382
|{n}
|{n}
383
|Sets the seed value for the example number sequence.^[<<note-number,1>>]^
384
385

|figure-caption
386
387
|_any_ +
`*Figure*`
388
|{y}
389
|{n}
390
391
392
|Text used to label images and figures.

|figure-number
393
|_number_ +
394
(`0`)
395
396
|{n}
|{n}
397
|Sets the seed value for the figure number sequence.^[<<note-number,1>>]^
398
399

|important-caption
400
401
|_any_ +
`*Important*`
402
|{y}
403
|{n}
404
405
406
|Text used to label IMPORTANT admonitions when icons are not enabled.

|lang
407
408
409
|_valid XML language code_ +
(`en`)
|{n}
410
|{y}
411
|Language used on root element of the output document.
412
413

|last-update-label
414
415
416
|_any_ +
`*Last updated*`
|{y}
417
418
419
420
421
|{y}
|Text used for “Last updated” label in footer.

|listing-caption
|_any_
422
423
|{n}
|{n}
424
425
426
|Text used to label listing blocks.

|listing-number
427
|_number_ +
428
(`0`)
429
430
|{n}
|{n}
431
|Sets the seed value for the listing number sequence.^[<<note-number,1>>]^
432
433

|manname-title
434
435
436
|_any_ +
(`Name`)
|{n}
437
438
439
440
441
|{y}
|Label for program name section in the man page.

|nolang
|_empty_
442
|{n}
443
444
445
446
|{y}
|Prevents `lang` attribute from being added to root element of the output document.

|note-caption
447
448
|_any_ +
`*Note*`
449
|{y}
450
|{n}
451
452
|Text used to label NOTE admonitions when icons aren't enabled.

453
454
455
456
|part-refsig
|_any_ +
`*Part*`
|{y}
457
|{n}
458
459
460
461
|Signifier added to Part titles in cross references.
_Book doctype only_.

|part-signifier
462
|_any_
463
464
465
466
467
468
469
470
471
|{n}
|{n}
|xref:sections:chapters.adoc[Label added to level-0 section titles (parts)].
_Book doctype only_.

|preface-title
|_any_
|{n}
|{n}
472
473
474
|Title text for an anonymous preface when `doctype` is `book`.

|section-refsig
475
476
|_any_ +
`*Section*`
477
|{y}
478
|{n}
479
480
481
|Signifier added to title of numbered sections in cross reference text.

|table-caption
482
483
|_any_ +
`*Table*`
484
|{y}
485
|{n}
486
487
488
|Text of label prefixed to table titles.

|table-number
489
|_number_ +
490
(`0`)
491
492
|{n}
|{n}
493
|Sets the seed value for the table number sequence.^[<<note-number,1>>]^
494
495

|tip-caption
496
497
|_any_ +
`*Tip*`
498
|{y}
499
|{n}
500
501
502
|Text used to label TIP admonitions when icons aren't enabled.

|toc-title
503
504
505
|_any_ +
`*Table of Contents*`
|{y}
506
507
508
509
|{y}
|xref:toc:title.adoc[Title for table of contents].

|untitled-label
510
511
512
|_any_ +
`*Untitled*`
|{y}
513
514
515
|{y}
|Default document title if document doesn't have a document title.

516
517
518
|version-label
|_any_ +
`*Version*`
519
520
|{y}
|{y}
521
522
523
524
525
|See xref:document:version-label.adoc[].

|warning-caption
|_any_ +
`*Warning*`
526
|{y}
527
|{n}
528
529
530
|Text used to label TIP admonitions when icons aren't enabled.
|===

531
== Document metadata attributes
532

533
[cols="30m,20,^10,^10,30"]
534
|===
535
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
536
537
538

|app-name
|_any_
539
|{n}
540
541
542
543
544
|{y}
|Adds `application-name` meta element for mobile devices inside HTML document head.

|author
|_any_
545
|Extracted from author info line
546
547
548
549
550
551
|{y}
|Can be set automatically via the author info line or explicitly.
See xref:document:author-information.adoc[].

|authorinitials
|_any_
552
|Extracted from `author` attribute
553
554
555
556
557
558
|{y}
|Derived from the author attribute by default.
See xref:document:author-information.adoc[].

|authors
|_any_
559
|Extracted from author info line
560
561
562
563
564
565
566
|{y}
|Can be set automatically via the author info line or explicitly as a comma-separated value list.
See xref:document:author-information.adoc[].

|copyright
|_any_
|{n}
567
|{y}
568
569
570
571
|Adds `copyright` meta element in HTML document head.

|doctitle
|_any_
572
|Yes, if document has a doctitle
573
574
575
576
577
578
|{y}
|See xref:document:title.adoc#reference-doctitle[doctitle attribute].

|description
|_any_
|{n}
579
|{y}
580
581
582
583
|Adds xref:document:metadata.adoc#description[description] meta element in HTML document head.

|email
|_any_
584
|Extracted from author info line
585
586
587
588
589
590
|{y}
|Can be any inline macro, such as a URL.
See xref:document:author-information.adoc[].

|firstname
|_any_
591
|Extracted from author info line
592
593
594
595
596
|{y}
|See xref:document:author-information.adoc[].

|front-matter
|_any_
597
|Yes, if front matter is captured
598
599
600
601
602
603
|n/a
|If `skip-front-matter` is set via the API or CLI, any YAML-style frontmatter skimmed from the top of the document is stored in this attribute.

|keywords
|_any_
|{n}
604
|{y}
605
606
607
608
|Adds xref:document:metadata.adoc#keywords[keywords] meta element in HTML document head.

|lastname
|_any_
609
|Extracted from author info line
610
611
612
613
614
|{y}
|See xref:document:author-information.adoc[].

|middlename
|_any_
615
|Extracted from author info line
616
617
618
619
620
621
|{y}
|See xref:document:author-information.adoc[].

|orgname
|_any_
|{n}
622
|{y}
623
624
625
626
|Adds `<orgname>` element value to DocBook info element.

|revdate
|_any_
627
|Extracted from revision info line
628
629
630
631
632
|{y}
|See xref:document:revision-information.adoc[].

|revremark
|_any_
633
|Extracted from revision info line
634
635
636
637
638
|{y}
|See xref:document:revision-information.adoc[].

|revnumber
|_any_
639
|Extracted from revision info line
640
641
642
643
644
645
|{y}
|See xref:document:revision-information.adoc[].

|title
|_any_
|{n}
646
|{y}
647
648
649
650
651
|Value of `<title>` element in HTML `<head>` or main DocBook `<info>` of output document.
Used as a fallback when the document title is not specified.
See xref:document:title.adoc#title-attr[title attribute].
|===

652
== Section title and table of contents attributes
653

654
[cols="30m,20,^10,^10,30"]
655
|===
656
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
657
658

|idprefix
659
660
|_valid XML ID start character_ +
`*_*`
661
662
663
664
665
666
|{y}
|{n}
|Prefix of auto-generated section IDs.
See xref:sections:id-prefix-and-separator.adoc#prefix[Change the ID prefix].

|idseparator
667
668
|_valid XML ID character_ +
`*_*`
669
670
671
672
673
674
|{y}
|{n}
|Word separator used in auto-generated section IDs.
See xref:sections:id-prefix-and-separator.adoc#separator[Change the ID word separator].

|leveloffset
675
676
|{startsb}+-{endsb}0{endash}5
|{n}
677
|{n}
678
|Increases or decreases level of headings below assignment.
679
A leading + or - makes the value relative.
680
681
682
//<<include-partitioning>>

|partnums
683
|_empty_
684
685
|{n}
|{n}
686
687
|Enables numbering of parts.
See xref:sections:part-numbers-and-labels.adoc#partnums[Number book parts].
688
689
690
691
_Book doctype only_.

|sectanchors
|_empty_
692
|{n}
693
694
695
696
697
698
699
700
701
702
703
704
|{n}
|xref:sections:title-links.adoc#anchor[Adds anchor in front of section title] on mouse cursor hover.

|sectids
|*_empty_*
|{y}
|{n}
|Generates and assigns an ID to any section that does not have an ID.
See xref:sections:ids.adoc#disable[Disable ID generation].

|sectlinks
|_empty_
705
|{n}
706
707
708
709
|{n}
|xref:sections:title-links.adoc[Turns section titles into self-referencing links].

|sectnums
710
711
|_empty_ +
`all`
712
713
714
715
716
|{n}
|{n}
|xref:sections:numbers.adoc[Numbers sections] to depth specified by `sectnumlevels`.

|sectnumlevels
717
|0{endash}5 +
718
(`3`)
719
|{n}
720
721
722
723
|{n}
|xref:sections:numbers.adoc#numlevels[Controls depth of section numbering].

|title-separator
724
|_any_
725
|{n}
726
|{y}
727
728
729
|Character used to xref:document:subtitle.adoc[separate document title and subtitle].

|toc
730
731
732
733
734
735
|_empty_[=`auto`] +
`auto` +
`left` +
`right` +
`macro` +
`preamble`
736
737
738
739
740
|{n}
|{y}
|Turns on xref:toc:index.adoc[table of contents] and specifies xref:toc:position.adoc[its location].

|toclevels
741
|1{endash}5 +
742
(`2`)
743
|{n}
744
|{y}
745
746
747
748
|xref:toc:section-depth.adoc[Maximum section level to display].

|fragment
|_empty_
749
750
|{n}
|{y}
751
752
753
754
755
|Informs parser that document is a fragment and that it shouldn't enforce proper section nesting.
|===

== General content and formatting attributes

756
[cols="30m,20,^10,^10,30"]
757
|===
758
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
759
760

|asset-uri-scheme
761
762
763
|_empty_ +
`http` +
(`https`)
764
765
766
767
768
769
770
|{n}
|{y}
|Controls protocol used for assets hosted on a CDN.

|cache-uri
|_empty_
|{n}
771
|{y}
772
773
774
775
776
|Cache content read from URIs.
//<<caching-uri-content>>

|data-uri
|_empty_
777
|{n}
778
779
780
781
782
|{y}
|Embed graphics as data-uri elements in HTML elements so file is completely self-contained.
//<<managing-images>>

|docinfo
783
784
785
786
787
788
789
|_empty_[=`private`] +
`shared` +
`private` +
`shared-head` +
`private-head` +
`shared-footer` +
`private-footer`
790
791
792
793
794
795
|{n}
|{y}
|Read input from one or more DocBook info files.
//<<naming-docinfo-files>>

|docinfodir
796
|_directory path_
797
|{n}
798
799
|{y}
|Location of docinfo files.
800
Defaults to directory of source file if not specified.
801
802
803
//<<locating-docinfo-files>>

|docinfosubs
804
805
806
|_comma-separated substitution names_ +
(`attributes`)
|{n}
807
808
809
810
811
|{y}
|AsciiDoc substitutions that are applied to docinfo content.
//<<attribute-substitution-in-docinfo-files>>

|doctype
812
813
814
815
|`*article*` +
`book` +
`inline` +
`manpage`
816
817
818
819
820
821
|{y}
|{y}
|Output document type.
//<<document-types>>

|eqnums
822
823
824
825
|_empty_[=`AMS`] +
`AMS` +
`all` +
`none`
826
827
828
829
830
831
832
|{n}
|{y}
|Controls automatic equation numbering on LaTeX blocks in HTML output (MathJax).
If the value is AMS, only LaTeX content enclosed in an `+\begin{equation}...\end{equation}+` container will be numbered.
If the value is all, then all LaTeX blocks will be numbered.
See https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numbering[equation numbering in MathJax].

833
|hardbreaks-option
834
835
|_empty_
|{n}
836
|{n}
837
|xref:blocks:hard-line-breaks.adoc#per-document[Preserve hard line breaks].
838
839
840

|hide-uri-scheme
|_empty_
841
842
|{n}
|{n}
843
|xref:macros:links.adoc#hide-uri-scheme[Hides URI scheme] for raw links.
844
845

|media
846
847
848
|`prepress` +
`print` +
(`screen`)
849
850
851
|{n}
|{y}
|Specifies media type of output and enables behavior specific to that media type.
852
_PDF converter only_.
853
854
855

|nofooter
|_empty_
856
|{n}
857
858
859
860
861
862
|{y}
|Turns off footer.
//<<footer-docinfo-files>>

|nofootnotes
|_empty_
863
|{n}
864
865
866
867
868
869
|{y}
|Turns off footnotes.
//<<user-footnotes>>

|noheader
|_empty_
870
|{n}
871
872
873
874
|{y}
|Turns off header.
//<<doc-header>>

875
876
877
878
879
880
881
|notitle
|_empty_
|{n}
|{y}
|xref:document:title.adoc#hide-or-show[Hides the doctitle in an embedded document].
Mutually exclusive with the `showtitle` attribute.

882
|outfilesuffix
883
884
|*_file extension_* +
_ex._ .html
885
|{y}
886
887
888
889
890
|{y}
|File extension of output file, including dot (`.`), such as `.html`.
// <<navigating-between-source-files>>

|pagewidth
891
|_integer_ +
892
(`425`)
893
894
895
896
897
|{n}
|{y}
|Page width used to calculate the absolute width of tables in the DocBook output.

|relfileprefix
898
899
900
901
|_empty_ +
_path segment_
|{n}
|{n}
902
903
904
905
|The path prefix to add to relative xrefs.
//<<navigating-between-source-files>>

|relfilesuffix
906
|*_file extension_* +
907
908
_path segment_ +
_ex._ .html
909
|{y}
910
|{n}
911
|The path suffix (e.g., file extension) to add to relative xrefs.
912
Defaults to the value of the `outfilesuffix` attribute.
913
914
915
916
917
(Preferred over modifying outfilesuffix).
//|<<navigating-between-source-files>>

|show-link-uri
|_empty_
918
919
|{n}
|{n}
920
|Prints the URI of a link after the link text.
921
922
923
924
925
_PDF converter only_.

|showtitle
|_empty_
|{n}
926
927
|{y}
|xref:document:title.adoc#hide-or-show[Displays the doctitle in an embedded document].
928
929
930
Mutually exclusive with the `notitle` attribute.

|stem
931
932
933
|`_empty_`[=`asciimath`] +
`asciimath` +
`latexmath`
934
935
936
937
938
|{n}
|{y}
|Enables xref:stem:stem.adoc[mathematics processing and interpreter].

|tabsize
939
940
|_integer_ (≥ 0)
|{n}
941
942
943
944
|{n}
|Converts tabs to spaces in verbatim content blocks (e.g., listing, literal).

|webfonts
945
946
|*_empty_*
|{y}
947
|{y}
948
|Control whether webfonts are loaded when using the default stylesheet.
949
950
When set to empty, uses the default font collection from Google Fonts.
A non-empty value replaces the `family` query string parameter in the Google Fonts URL.
951
952
953
//<<applying-a-theme>> and {url-org}/asciidoctor.org/issues/410[issue #410^]

|xrefstyle
954
955
956
|`full` +
`short` +
`basic`
957
958
959
960
961
962
963
964
|{n}
|{n}
|xref:macros:xref-text-and-style.adoc#cross-reference-styles[Formatting style to apply to cross reference text].
//_Introduced in 1.5.6._
|===

== Image and icon attributes

965
[cols="30m,20,^10,^10,30"]
966
|===
967
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
968
969

|iconfont-cdn
970
971
|_url_ +
(default CDN URL)
972
|{n}
973
|{y}
974
975
|If not specified, uses the cdnjs.com service.
Overrides CDN used to link to the Font Awesome stylesheet.
976
977

|iconfont-name
978
979
980
|_any_ +
(`font-awesome`)
|{n}
981
982
983
984
985
|{y}
|Overrides the name of the icon font stylesheet.
//<<icons>>

|iconfont-remote
986
987
|*_empty_*
|{y}
988
989
|{y}
|Allows use of a CDN for resolving the icon font.
990
Only relevant used when value of `icons` attribute is `font`.
991
992

|icons
993
994
995
|_empty_[=`image`] +
`image` +
`font`
996
997
|{n}
|{y}
998
|Chooses xref:macros:icons.adoc#icons-attribute[images or font icons] instead of text for admonitions.
999
Any other value is assumed to be an icontype and sets the value to empty (image-based icons).
1000
1001

|iconsdir
1002
1003
1004
|_directory path_ +
_url_ +
_ex._ ./images/icons
1005
1006
1007
|{y}
|{n}
|Location of non-font-based image icons.
1008
Defaults to the _icons_ folder under `imagesdir` if `imagesdir` is specified and `iconsdir` is not specified.
1009
1010

|icontype
1011
1012
1013
1014
1015
|`jpg` +
(`png`) +
`gif` +
`svg`
|{n}
1016
1017
|{n}
|File type for image icons.
1018
Only relevant when using image-based icons.
1019
1020

|imagesdir
1021
1022
1023
|*_empty_* +
_directory path_ +
_url_
1024
1025
1026
1027
1028
|{y}
|{n}
|Location of image files.
|===

1029
== Source highlighting and formatting attributes
1030

1031
[cols="30m,20,^10,^10,30"]
1032
|===
1033
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
1034
1035

|coderay-css
1036
1037
|(`class`) +
`style`
1038
|{n}
1039
|{y}
1040
1041
1042
|Controls whether CodeRay uses CSS classes or inline styles.

|coderay-linenums-mode
1043
1044
|`inline` +
(`table`)
1045
|{n}
1046
|{y}
1047
1048
1049
1050
1051
|Sets how CodeRay inserts line numbers into source listings.

|coderay-unavailable
|_empty_
|{n}
1052
|{y}
1053
1054
1055
|Tells processor not to load CodeRay.

|highlightjsdir
1056
|_directory path_ +
1057
1058
_url_ +
(default CDN URL)
1059
1060
1061
1062
1063
|{n}
|{y}
|Location of the highlight.js source code highlighter library.

|highlightjs-theme
1064
1065
|_highlight.js style name_ +
(`github`)
1066
|{n}
1067
|{y}
1068
1069
1070
|Name of theme used by highlight.js.

|prettifydir
1071
|_directory path_ +
1072
1073
_url_ +
(default CDN URL)
1074
1075
1076
1077
1078
|{n}
|{y}
|Location of non-CDN prettify source code highlighter library.

|prettify-theme
1079
1080
|_prettify style name_ +
(`prettify`)
1081
|{n}
1082
|{y}
1083
1084
1085
|Name of theme used by prettify.

|prewrap
1086
|*_empty_*
1087
|{y}
1088
|{n}
1089
|xref:asciidoctor:html-backend:verbatim-line-wrap.adoc[Wrap wide code listings].
1090
1091

|pygments-css
1092
1093
|(`class`) +
`style`
1094
|{n}
1095
|{y}
1096
1097
1098
|Controls whether Pygments uses CSS classes or inline styles.

|pygments-linenums-mode
1099
1100
|(`table`) +
`inline`
1101
|{n}
1102
|{y}
1103
1104
1105
|Sets how Pygments inserts line numbers into source listings.

|pygments-style
1106
1107
|_Pygments style name_ +
(`default`)
1108
|{n}
1109
|{y}
1110
1111
1112
1113
1114
|Name of style used by Pygments.

|pygments-unavailable
|_empty_
|{n}
1115
|{y}
1116
1117
1118
|Tells the processor not to load Pygments.

|source-highlighter
1119
1120
1121
1122
|`coderay` +
`highlight.js` +
`pygments` +
`rouge`
1123
1124
1125
|{n}
|{y}
|xref:verbatim:source-highlighter.adoc[Specifies source code highlighter].
1126
Any other value is permitted, but must be supported by a custom syntax highlighter adapter.
1127
1128

|source-indent
1129
1130
|_integer_
|{n}
1131
1132
1133
1134
1135
|{n}
|Normalize block indentation in source code listings.
//<<normalize-block-indentation>>

|source-language
1136
|_source code language name_
1137
1138
|{n}
|{n}
1139
1140
1141
1142
|xref:verbatim:source-highlighter.adoc[Default language for source code blocks].

|source-linenums-option
|_empty_
1143
1144
|{n}
|{n}
1145
1146
1147
1148
1149
1150
|Turns on line numbers for source code listings.
//_Introduced in 1.5.6._
|===

== HTML styling attributes

1151
[cols="30m,20,^10,^10,30"]
1152
|===
1153
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
1154
1155

|copycss
1156
|*_empty_* +
1157
_file path_
1158
|{y}
1159
1160
|{y}
|Copy CSS files to output.
1161
Only relevant when the `linkcss` attribute is set.
1162
1163
1164
//<<applying-a-theme>>

|css-signature
1165
|_valid XML ID_
1166
1167
1168
1169
1170
1171
1172
1173
|{n}
|{y}
|Assign value to `id` attribute of HTML `<body>` element.
*Preferred approach is to assign an ID to document title*.

|linkcss
|_empty_
|{n}
1174
|{y}
1175
1176
1177
1178
1179
1180
1181
|Links to stylesheet instead of embedding it.
Can't be unset in SECURE mode.
//<<styling-the-html-with-css>>

|max-width
|CSS length (e.g. 55em, 12cm, etc)
|{n}
1182
|{y}
1183
1184
1185
1186
1187
|Constrains maximum width of document body.
*Not recommended.
Use CSS stylesheet instead.*

|stylesdir
1188
1189
1190
|_directory path_ +
_url_ +
`*.*`
1191
1192
1193
1194
1195
1196
|{y}
|{y}
|Location of CSS stylesheets.
//<<creating-a-theme>>

|stylesheet
1197
1198
|*_empty_* +
_file path_
1199
1200
1201
|{y}
|{y}
|CSS stylesheet file name.
1202
An empty value tells the converter to use the default stylesheet.
1203
1204
1205
//<<applying-a-theme>>

|toc-class
1206
1207
|_valid CSS class name_ +
`*toc2*` or (`toc`)
1208
|{n}
1209
|{y}
1210
1211
1212
1213
1214
1215
|CSS class on the table of contents container.
//<<user-toc>>
|===

== Manpage attributes

1216
The attribute in this section are only relevant when using the manpage doctype and/or backend.
1217

1218
[cols="30m,20,^10,^10,30"]
1219
|===
1220
.>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
1221
1222
1223

|mantitle
|_any_
1224
|Based on content.
1225
1226
1227
1228
1229
1230
|{y}
|Metadata for man page output.
//<<man-pages>>

|manvolnum
|_any_
1231
|Based on content.
1232
1233
1234
1235
1236
1237
|{y}
|Metadata for man page output.
//<<man-pages>>

|manname
|_any_
1238
|Based on content.
1239
1240
1241
1242
1243
1244
|{y}
|Metadata for man page output.
//<<man-pages>>

|manpurpose
|_any_
1245
|Based on content
1246
1247
1248
1249
1250
|{y}
|Metadata for man page output.
//<<man-pages>>

|man-linkstyle
1251
1252
|_link format pattern_ +
(`blue R <>`)
1253
|{n}
1254
|{y}
1255
1256
1257
1258
1259
1260
|Link style in man page output.
//<<man-pages>>

|mansource
|_any_
|{n}
1261
|{y}
1262
1263
1264
1265
1266
1267
|Source (e.g., application and version) the man page describes.
//<<man-pages>>

|manmanual
|_any_
|{n}
1268
|{y}
1269
1270
1271
1272
1273
1274
|Manual name displayed in the man page footer.
//<<man-pages>>
|===

== Security attributes

1275
Since these attributes deal with security, they can only be set from the API or CLI.
1276

1277
[cols="30m,20,^10,^10,30"]
1278
|===
1279
.>|Name .>|Allowable Values .>|Set By Default .>|API/CLI Only .>|Notes
1280
1281
1282

|allow-uri-read
|_empty_
1283
|{n}
1284
1285
1286
1287
1288
|{y}
|Allows data to be read from URLs.
//<<include-uri>>

|max-attribute-value-size
1289
|_integer_ (≥ 0) +
1290
`*4096*`
1291
|If safe mode is SECURE
1292
1293
|{y}
|Limits maximum size (in bytes) of a resolved attribute value.