Merge pull request #263 from lordofthejars/issue-260

resolves #263 Documents how safe mode works

README.adoc

@@ -303,6 +303,32 @@ StringBuffer htmlBuffer = writer.getBuffer();
 System.out.println(htmlBuffer.toString());
 ----
 
+==== Safe mode and file system access
+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.
+
+When Asciidoctor (and AsciidoctorJ) is used as _API_, it uses `SECURE` safe mode by default.
+This mode is the most restrictive one and in summary it disallows the document from attempting to read files from the file system and including their contents into the document.
+
+We recommend you to set `SAFE` safe mode when rendering AsciiDoc documents using AsciidoctorJ to have almost all Asciidoctor features such as _icons_, _include directive_ or retrieving content from _URIs_ enabled.
+
+Safe mode is set as option when a document is rendered.
+For example:
+
+[source, java]
+----
+import static org.asciidoctor.OptionsBuilder.options;
+
+Map<String, Object> options = options().safe(SafeMode.SAFE)
+                                       .asMap();
+
+String outfile = asciidoctor.convertFile(new File("sample.adoc"), options);
+----
+
+We are going to explain in more detail options in <<conversion-options, next section>>.
+
+
+You can read more about safe modes in http://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely
+
 === Conversion options
 
 Asciidoctor supports numerous options, such as: