You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
45 lines
2.4 KiB
45 lines
2.4 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Running Asciidoctor Securely: Set attributes based on the safe mode
|
||
|
|
////
|
||
|
|
|
||
|
|
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:
|
||
|
|
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
\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.
|
||
|
|
|
||
|
|
////
|
||
|
|
Allow the include directive to import a file from a URI.
|
||
|
|
|
||
|
|
Example:
|
||
|
|
|
||
|
|
include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
|
||
|
|
|
||
|
|
To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater.
|
||
|
|
Since this is a potentially dangerous feature, it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI.
|
||
|
|
|
||
|
|
I decided the following defaults for the header_footer option make the most sense:
|
||
|
|
|
||
|
|
true if using the cli (use -s to disable, consistent with asciidoc)
|
||
|
|
false if using the API, unless converting directly to a file, in which case true is the default
|
||
|
|
The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting.
|
||
|
|
|
||
|
|
The reason I think the header_footer default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now.
|
||
|
|
////
|