Set Attributes By Safe Mode

Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. Each level includes the restrictions enabled in the prior security level.

Asciidoctor provides access to the current safe mode through built-in attributes. You can use these attributes to enable or disable content based on the current safe mode of the processor.

The safe mode can be referenced by one of the following attributes:

  • The value of the safe-mode-name attribute (e.g., unsafe, safe, etc.)

  • The value of the safe-mode-level attribute (e.g., 0, 10, etc.)

  • The presense of the safe-mode-<name> attribute, where <name> is the safe mode name.

The attributes in the next example define replacement text for features that are disabled in high security environments:

ifdef::safe-mode-secure[]
Link to chapters instead of including them.
endif::safe-mode-secure[]

This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure.

You can set the asciidoctor:cli:set-safe-mode.adoc and the API.