From 79c454cb8080b3b4172c1575f3e01ac4d0931b73 Mon Sep 17 00:00:00 2001
From: Xavier Coulon <xcoulon@redhat.com>
Date: Sat, 7 Mar 2020 18:07:02 +0100
Subject: [PATCH] feat(cli): support attributes set/reset in CLI (#495)

API break: using a new 'configuration.Configuration' parameter to wrap
all the settings at the `libasciidoc.ConvertToHTML`
level

Fixes #484

Signed-off-by: Xavier Coulon <xcoulon@redhat.com>
---
 README.adoc                                   |  14 +-
 cmd/libasciidoc/root_cmd.go                   |  40 +++-
 cmd/libasciidoc/root_cmd_test.go              |  34 +++-
 cmd/libasciidoc/test/doc_with_attributes.adoc |   5 +
 go.sum                                        |  10 +-
 libasciidoc.go                                |  23 ++-
 libasciidoc_test.go                           |  14 +-
 pkg/configuration/configuration.go            |  98 +++++++++
 pkg/configuration/macro_template.go           |   8 +
 pkg/parser/document_preprocessing.go          |  28 +--
 pkg/parser/document_processing.go             |  35 ++--
 ...document_processing_apply_substitutions.go |   8 +-
 ...ent_processing_apply_substitutions_test.go | 147 +++++++++++---
 pkg/parser/file_inclusion.go                  |  27 ++-
 pkg/parser/file_inclusion_test.go             |  83 +++++++-
 pkg/renderer/context.go                       | 188 ++++++++++--------
 pkg/renderer/html5/article_adoc_test.go       |   6 +-
 pkg/renderer/html5/document_details.go        |   3 +-
 pkg/renderer/html5/document_details_test.go   |   8 +-
 pkg/renderer/html5/elements.go                |   2 +-
 pkg/renderer/html5/file_inclusion_test.go     |  24 +--
 pkg/renderer/html5/html5.go                   |   9 +-
 pkg/renderer/html5/html5_test.go              |   8 +-
 pkg/renderer/html5/inline_elements.go         |   6 +-
 pkg/renderer/html5/paragraph.go               |   8 +-
 pkg/renderer/html5/user_macro.go              |   2 +-
 pkg/renderer/html5/user_macro_test.go         |  18 +-
 pkg/renderer/options.go                       |  86 --------
 pkg/types/document_attributes.go              |  89 ++++++---
 pkg/types/document_attributes_test.go         |  79 ++++++--
 pkg/types/element_attributes.go               |  16 +-
 pkg/types/types.go                            |  12 +-
 pkg/types/types_test.go                       |  49 +++--
 test/supported_fixtures_test.go               |   4 +-
 testsupport/document_attributes.go            |   3 +-
 testsupport/document_metadata.go              |   7 +-
 testsupport/document_metadata_test.go         |   4 +-
 testsupport/html5_template_matcher.go         |   4 +-
 testsupport/include_preamble.go               |   3 +-
 .../include_table_of_contents_placeholder.go  |   3 +-
 testsupport/parse_document.go                 |   3 +-
 testsupport/parse_draft_document.go           |   4 +-
 testsupport/render_html5.go                   |  62 ++----
 testsupport/table_of_contents.go              |   3 +-
 44 files changed, 820 insertions(+), 467 deletions(-)
 create mode 100644 cmd/libasciidoc/test/doc_with_attributes.adoc
 create mode 100644 pkg/configuration/configuration.go
 create mode 100644 pkg/configuration/macro_template.go
 delete mode 100644 pkg/renderer/options.go

diff --git a/README.adoc b/README.adoc
index c453e797..4788b9a4 100644
--- a/README.adoc
+++ b/README.adoc
@@ -58,21 +58,21 @@ Libasciidoc provides 2 functions to convert an Asciidoc content into HTML:
 
 1. Converting an `io.Reader` into an HTML document:
 
-    func ConvertToHTML(ctx context.Context, source io.Reader, output io.Writer, options renderer.Option...) (map[string]interface{}, error)
+    ConvertToHTML(r io.Reader, output io.Writer, config configuration.Configuration) (types.Metadata, error) 
 
 2. Converting a file (given its name) into an HTML document:
 
-    func ConvertFileToHTML(ctx context.Context, filename string, output io.Writer, options renderer.Option...) (map[string]interface{}, error)
+   ConvertFileToHTML(output io.Writer, config configuration.Configuration) (types.Metadata, error)
 
-where the returned `map[string]interface{}` object contains the document's title which is not part of the generated HTML `<body>` part, as well as the other attributes of the source document.
+where the returned `types.Metadata` object contains the document's title which is not part of the generated HTML `<body>` part, as well as the other attributes of the source document.
 
-For now, the sole option to pass as a last argument is `renderer.IncludeHeaderFooter` to include the `<header>` and `<footer>` elements in the generated HTML document or not. Default is `false`, which means that only the `<body>` part of the HTML document is generated.
+All options/settings are passed via the `config` parameter.
 
 === Macro definition
 
-The user can define a macro by calling `renderer.DefineMacro()` and passing return value to conversion functions.
+The user can define a macro by calling `renderer.WithMacroTemplate()` and passing return value to conversion functions.
 
-`renderer.DefineMacro()` defines a macro by the given name and associates the given template. The template is an implementation of `renderer.MacroTemplate` interface (ex. `text.Template`)
+`renderer.WithMacroTemplate()` defines a macro by the given name and associates the given template. The template is an implementation of `renderer.MacroTemplate` interface (ex. `text.Template`)
 
 Libasciidoc calls `Execute()` method and passes `types.UserMacro` object to template when rendering.
 
@@ -85,7 +85,7 @@ var tmpl = template.Must(t.Parse(tmplStr))
 
 output := &strings.Builder{}
 content := strings.NewReader(`example::hello world[suffix=!!!!!]`)
-libasciidoc.ConvertToHTML(context.Background(), content, output, renderer.DefineMacro(tmpl.Name(), tmpl))
+libasciidoc.ConvertToHTML(context.Background(), content, output, renderer.WithMacroTemplate(tmpl.Name(), tmpl))
 ```
 
 == How to contribute
diff --git a/cmd/libasciidoc/root_cmd.go b/cmd/libasciidoc/root_cmd.go
index a34ddf85..bcee4e2f 100644
--- a/cmd/libasciidoc/root_cmd.go
+++ b/cmd/libasciidoc/root_cmd.go
@@ -9,8 +9,8 @@ import (
 	"path/filepath"
 
 	"github.com/bytesparadise/libasciidoc"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	logsupport "github.com/bytesparadise/libasciidoc/pkg/log"
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 
 	log "github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
@@ -23,6 +23,7 @@ func NewRootCmd() *cobra.Command {
 	var outputName string
 	var logLevel string
 	var css string
+	var attributes []string
 
 	rootCmd := &cobra.Command{
 		Use:   "libasciidoc [flags] FILE",
@@ -43,13 +44,19 @@ func NewRootCmd() *cobra.Command {
 			if len(args) == 0 {
 				return helpCommand.RunE(cmd, args)
 			}
-			for _, source := range args {
-				out, close := getOut(cmd, source, outputName)
+			attrs := parseAttributes(attributes)
+			for _, sourcePath := range args {
+				out, close := getOut(cmd, sourcePath, outputName)
 				if out != nil {
 					defer close()
-					path, _ := filepath.Abs(source)
+					path, _ := filepath.Abs(sourcePath)
 					log.Debugf("Starting to process file %v", path)
-					_, err := libasciidoc.ConvertFileToHTML(source, out, renderer.IncludeHeaderFooter(!noHeaderFooter), renderer.IncludeCSS(css))
+					config := configuration.NewConfiguration(
+						configuration.WithFilename(sourcePath),
+						configuration.WithAttributes(attrs),
+						configuration.WithCSS(css),
+						configuration.WithHeaderFooter(!noHeaderFooter))
+					_, err := libasciidoc.ConvertFileToHTML(out, config)
 					if err != nil {
 						return err
 					}
@@ -63,6 +70,7 @@ func NewRootCmd() *cobra.Command {
 	flags.StringVarP(&outputName, "out-file", "o", "", "output file (default: based on path of input file); use - to output to STDOUT")
 	flags.StringVar(&logLevel, "log", "warning", "log level to set [debug|info|warning|error|fatal|panic]")
 	flags.StringVar(&css, "css", "", "the path to the CSS file to link to the document")
+	flags.StringArrayVarP(&attributes, "attribute", "a", []string{}, "a document attribute to set in the form of name, name!, or name=value pair")
 	return rootCmd
 }
 
@@ -78,7 +86,7 @@ func newCloseFileFunc(c io.Closer) closeFunc {
 	}
 }
 
-func getOut(cmd *cobra.Command, source, outputName string) (io.Writer, closeFunc) {
+func getOut(cmd *cobra.Command, sourcePath, outputName string) (io.Writer, closeFunc) {
 	if outputName == "-" {
 		// outfile is STDOUT
 		return cmd.OutOrStdout(), defaultCloseFunc()
@@ -89,9 +97,9 @@ func getOut(cmd *cobra.Command, source, outputName string) (io.Writer, closeFunc
 			log.Warnf("Cannot create output file - %v, skipping", outputName)
 		}
 		return outfile, newCloseFileFunc(outfile)
-	} else if source != "" {
-		// outfile is based on source
-		path, _ := filepath.Abs(source)
+	} else if sourcePath != "" {
+		// outfile is based on sourcePath
+		path, _ := filepath.Abs(sourcePath)
 		outname := strings.TrimSuffix(path, filepath.Ext(path)) + ".html"
 		outfile, err := os.Create(outname)
 		if err != nil {
@@ -102,3 +110,17 @@ func getOut(cmd *cobra.Command, source, outputName string) (io.Writer, closeFunc
 	}
 	return cmd.OutOrStdout(), defaultCloseFunc()
 }
+
+// converts the `name`, `!name` and `name=value` into a map
+func parseAttributes(attributes []string) map[string]string {
+	result := make(map[string]string, len(attributes))
+	for _, attr := range attributes {
+		data := strings.Split(attr, "=")
+		if len(data) > 1 {
+			result[data[0]] = data[1]
+		} else {
+			result[data[0]] = ""
+		}
+	}
+	return result
+}
diff --git a/cmd/libasciidoc/root_cmd_test.go b/cmd/libasciidoc/root_cmd_test.go
index ef915ce3..1ddaf23e 100644
--- a/cmd/libasciidoc/root_cmd_test.go
+++ b/cmd/libasciidoc/root_cmd_test.go
@@ -11,7 +11,6 @@ import (
 )
 
 var _ = Describe("root cmd", func() {
-	RegisterFailHandler(Fail)
 
 	It("render with STDOUT output", func() {
 		// given
@@ -68,6 +67,38 @@ var _ = Describe("root cmd", func() {
 		Expect(buf.String()).ToNot(ContainSubstring(`<div id="footer">`))
 	})
 
+	It("render with attribute set", func() {
+		// given
+		root := main.NewRootCmd()
+		buf := new(bytes.Buffer)
+		root.SetOutput(buf)
+		root.SetArgs([]string{"-s", "-o", "-", "-afoo1=bar1", "-afoo2=bar2", "test/doc_with_attributes.adoc"})
+		// when
+		err := root.Execute()
+		// then
+		Expect(err).ToNot(HaveOccurred())
+		Expect(buf.String()).ToNot(BeEmpty())
+		Expect(buf.String()).To(Equal(`<div class="paragraph">
+<p>bar1 and bar2</p>
+</div>`))
+	})
+
+	It("render with attribute reset", func() {
+		// given
+		root := main.NewRootCmd()
+		buf := new(bytes.Buffer)
+		root.SetOutput(buf)
+		root.SetArgs([]string{"-s", "-o", "-", "-afoo1=bar1", "-a!foo2", "test/doc_with_attributes.adoc"})
+		// when
+		err := root.Execute()
+		// then
+		Expect(err).ToNot(HaveOccurred())
+		Expect(buf.String()).ToNot(BeEmpty())
+		Expect(buf.String()).To(Equal(`<div class="paragraph">
+<p>bar1 and {foo2}</p>
+</div>`))
+	})
+
 	It("render multiple files", func() {
 		// given
 		root := main.NewRootCmd()
@@ -103,4 +134,5 @@ var _ = Describe("root cmd", func() {
 		// then
 		Expect(err).ToNot(HaveOccurred())
 	})
+
 })
diff --git a/cmd/libasciidoc/test/doc_with_attributes.adoc b/cmd/libasciidoc/test/doc_with_attributes.adoc
new file mode 100644
index 00000000..116e4efc
--- /dev/null
+++ b/cmd/libasciidoc/test/doc_with_attributes.adoc
@@ -0,0 +1,5 @@
+:foo1: FOO1
+
+:!foo1:
+
+{foo1} and {foo2}
\ No newline at end of file
diff --git a/go.sum b/go.sum
index d8548665..5a1d56cb 100644
--- a/go.sum
+++ b/go.sum
@@ -1,8 +1,11 @@
+github.com/alecthomas/assert v0.0.0-20170929043011-405dbfeb8e38 h1:smF2tmSOzy2Mm+0dGI2AIUHY+w0BUc+4tn40djz7+6U=
 github.com/alecthomas/assert v0.0.0-20170929043011-405dbfeb8e38/go.mod h1:r7bzyVFMNntcxPZXK3/+KdruV1H5KSlyVY0gc+NgInI=
 github.com/alecthomas/chroma v0.7.1 h1:G1i02OhUbRi2nJxcNkwJaY/J1gHXj9tt72qN6ZouLFQ=
 github.com/alecthomas/chroma v0.7.1/go.mod h1:gHw09mkX1Qp80JlYbmN9L3+4R5o6DJJ3GRShh+AICNc=
+github.com/alecthomas/colour v0.0.0-20160524082231-60882d9e2721 h1:JHZL0hZKJ1VENNfmXvHbgYlbUOvpzYzvy2aZU5gXVeo=
 github.com/alecthomas/colour v0.0.0-20160524082231-60882d9e2721/go.mod h1:QO9JBoKquHd+jz9nshCh40fOfO+JzsoXy8qTHF68zU0=
 github.com/alecthomas/kong v0.2.1-0.20190708041108-0548c6b1afae/go.mod h1:+inYUSluD+p4L8KdviBSgzcqEjUQOfC5fQDRFuc36lI=
+github.com/alecthomas/repr v0.0.0-20180818092828-117648cd9897 h1:p9Sln00KOTlrYkxI1zYWl1QLnEqAqEARBEYa8FQnQcY=
 github.com/alecthomas/repr v0.0.0-20180818092828-117648cd9897/go.mod h1:xTS7Pm1pD1mvyM075QCDSRqH6qRLXylzS24ZTpRiSzQ=
 github.com/danwakefield/fnmatch v0.0.0-20160403171240-cbb64ac3d964 h1:y5HC9v93H5EPKqaS1UYVg1uYah5Xf51mBfIoWehClUQ=
 github.com/danwakefield/fnmatch v0.0.0-20160403171240-cbb64ac3d964/go.mod h1:Xd9hchkHSWYkEqJwUGisez3G1QY8Ryz0sdWrLPMGjLk=
@@ -24,6 +27,7 @@ github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANyt
 github.com/konsorten/go-windows-terminal-sequences v1.0.1 h1:mweAR1A6xJ3oS2pRaGiHgQ4OO8tzTaLawm8vnODuwDk=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
 github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU=
+github.com/mattn/go-isatty v0.0.4 h1:bnP0vzxcAdeI1zdubAl5PjU6zsERjGZb7raWodagDYs=
 github.com/mattn/go-isatty v0.0.4/go.mod h1:M+lRXTBqGeGNdLjl/ufCoiOlB5xdOkqRJdNxMWT7Zi4=
 github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
 github.com/mna/pigeon v1.0.1-0.20190909211542-7ee56e19b15c h1:QRaadf9Fu8xAfNDS8PvaM0VmY2FnYHlddtnIExKj68k=
@@ -35,8 +39,6 @@ github.com/onsi/ginkgo v1.10.1 h1:q/mM8GF/n0shIN8SaAZ0V+jnLPzen6WIVZdiwrRlMlo=
 github.com/onsi/ginkgo v1.10.1/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
 github.com/onsi/gomega v1.5.0 h1:izbySO9zDPmjJ8rDjLvkA2zJHIo+HkYXHnf7eN7SSyo=
 github.com/onsi/gomega v1.5.0/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY=
-github.com/pkg/errors v0.8.0 h1:WdK/asTD0HN+q6hsWO3/vpuAkAr+tw6aNJNDFFf0+qw=
-github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.8.1 h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -61,8 +63,6 @@ golang.org/x/crypto v0.0.0-20180904163835-0709b304e793 h1:u+LnwYTOOW7Ukr/fppxEb1
 golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 h1:VklqNMn3ovrHsnt90PveolxSbWFaJdECFbxSq0Mqo2M=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
-golang.org/x/crypto v0.0.0-20190909091759-094676da4a83 h1:mgAKeshyNqWKdENOnQsg+8dRTwZFIwFaO3HNl52sweA=
-golang.org/x/crypto v0.0.0-20190909091759-094676da4a83/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550 h1:ObdrDkeb4kJdCP557AjRjq69pTHfNouLtWZG7j9rPN8=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
@@ -91,8 +91,6 @@ golang.org/x/text v0.3.2 h1:tW2bmiBqwgJj/UpqtC8EpXEZVYOwU0yG4iWbprSVAcs=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190830223141-573d9926052a/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
-golang.org/x/tools v0.0.0-20190911225940-c7d52e45e2f2 h1:4m1a+ssoIi4N/776T3Dc79eRjDc5sEhMQXFAKoO3TM8=
-golang.org/x/tools v0.0.0-20190911225940-c7d52e45e2f2/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20191220234730-f13409bbebaf h1:K7C8vSrr0PeD/cgNkkjpByDFJqzjr2YDmm3VPRjGfJM=
 golang.org/x/tools v0.0.0-20191220234730-f13409bbebaf/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7 h1:9zdDQZ7Thm29KFXgAX/+yaf3eVbP7djjWp/dXAppNCc=
diff --git a/libasciidoc.go b/libasciidoc.go
index 9c45ee07..5618bfcc 100644
--- a/libasciidoc.go
+++ b/libasciidoc.go
@@ -7,12 +7,13 @@ import (
 	"os"
 	"time"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/parser"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	htmlrenderer "github.com/bytesparadise/libasciidoc/pkg/renderer/html5"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
-
 	"github.com/pkg/errors"
+
 	log "github.com/sirupsen/logrus"
 )
 
@@ -28,35 +29,35 @@ var (
 // ConvertFileToHTML converts the content of the given filename into an HTML document.
 // The conversion result is written in the given writer `output`, whereas the document metadata (title, etc.) (or an error if a problem occurred) is returned
 // as the result of the function call.
-func ConvertFileToHTML(filename string, output io.Writer, options ...renderer.Option) (types.Metadata, error) {
-	file, err := os.Open(filename)
+func ConvertFileToHTML(output io.Writer, config configuration.Configuration) (types.Metadata, error) {
+	file, err := os.Open(config.Filename)
 	if err != nil {
-		return types.Metadata{}, errors.Wrapf(err, "error opening %s", filename)
+		return types.Metadata{}, errors.Wrapf(err, "error opening %s", config.Filename)
 	}
 	defer file.Close()
 	// use the file mtime as the `last updated` value
-	stat, err := os.Stat(filename)
+	stat, err := os.Stat(config.Filename)
 	if err != nil {
-		return types.Metadata{}, errors.Wrapf(err, "error opening %s", filename)
+		return types.Metadata{}, errors.Wrapf(err, "error opening %s", config.Filename)
 	}
-	options = append(options, renderer.LastUpdated(stat.ModTime()))
-	return ConvertToHTML(filename, file, output, options...)
+	config.LastUpdated = stat.ModTime()
+	return ConvertToHTML(file, output, config)
 }
 
 // ConvertToHTML converts the content of the given reader `r` into a full HTML document, written in the given writer `output`.
 // Returns an error if a problem occurred
-func ConvertToHTML(filename string, r io.Reader, output io.Writer, options ...renderer.Option) (types.Metadata, error) {
+func ConvertToHTML(r io.Reader, output io.Writer, config configuration.Configuration) (types.Metadata, error) {
 	start := time.Now()
 	defer func() {
 		duration := time.Since(start)
 		log.Debugf("rendered the HTML output in %v", duration)
 	}()
 	log.Debugf("parsing the asciidoc source...")
-	doc, err := parser.ParseDocument(filename, r) //, parser.Debug(true))
+	doc, err := parser.ParseDocument(r, config) //, parser.Debug(true))
 	if err != nil {
 		return types.Metadata{}, err
 	}
-	rendererCtx := renderer.NewContext(doc, options...)
+	rendererCtx := renderer.NewContext(doc, config)
 	// insert tables of contents, preamble and process file inclusions
 	err = renderer.Prerender(rendererCtx)
 	if err != nil {
diff --git a/libasciidoc_test.go b/libasciidoc_test.go
index ee403d13..ef492c71 100644
--- a/libasciidoc_test.go
+++ b/libasciidoc_test.go
@@ -4,7 +4,7 @@ import (
 	"os"
 	"time"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 	. "github.com/bytesparadise/libasciidoc/testsupport"
 
@@ -113,7 +113,7 @@ a paragraph`
 			Expect(RenderHTML5Title(source)).To(Equal(expectedTitle))
 			Expect(DocumentMetadata(source, lastUpdated)).To(Equal(types.Metadata{
 				Title:       "a document title",
-				LastUpdated: lastUpdated.Format(renderer.LastUpdatedFormat),
+				LastUpdated: lastUpdated.Format(configuration.LastUpdatedFormat),
 				TableOfContents: types.TableOfContents{
 					Sections: []types.ToCSection{
 						{
@@ -175,7 +175,7 @@ a paragraph with _italic content_`
 			Expect(RenderHTML5Title(source)).To(Equal(expectedTitle))
 			Expect(DocumentMetadata(source, lastUpdated)).To(Equal(types.Metadata{
 				Title:       "a document title",
-				LastUpdated: lastUpdated.Format(renderer.LastUpdatedFormat),
+				LastUpdated: lastUpdated.Format(configuration.LastUpdatedFormat),
 				TableOfContents: types.TableOfContents{
 					Sections: []types.ToCSection{
 						{
@@ -215,10 +215,10 @@ a paragraph with _italic content_`
 </div>
 </div>
 </div>`
-			Expect(RenderHTML5Body(source, WithFilename("test.adoc"), renderer.LastUpdated(lastUpdated))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"), configuration.WithLastUpdated(lastUpdated))).To(Equal(expected))
 			Expect(DocumentMetadata(source, lastUpdated)).To(Equal(types.Metadata{
 				Title:       "",
-				LastUpdated: lastUpdated.Format(renderer.LastUpdatedFormat),
+				LastUpdated: lastUpdated.Format(configuration.LastUpdatedFormat),
 				TableOfContents: types.TableOfContents{
 					Sections: []types.ToCSection{
 						{
@@ -245,7 +245,7 @@ a paragraph with _italic content_`
 </div>
 </div>
 </div>`
-			Expect(RenderHTML5Body(source, WithFilename("tmp/foo.adoc"))).To(Equal(expectedContent))
+			Expect(RenderHTML5Body(source, configuration.WithFilename("tmp/foo.adoc"))).To(Equal(expectedContent))
 		})
 	})
 
@@ -281,7 +281,7 @@ Last updated {{.LastUpdated}}
 			filename := "test/includes/chapter-a.adoc"
 			stat, err := os.Stat(filename)
 			Expect(err).NotTo(HaveOccurred())
-			Expect(RenderHTML5Document(filename, renderer.IncludeCSS("path/to/style.css"))).To(MatchHTML5Template(expectedContent, stat.ModTime()))
+			Expect(RenderHTML5Document(filename, configuration.WithCSS("path/to/style.css"), configuration.WithHeaderFooter(true))).To(MatchHTML5Template(expectedContent, stat.ModTime()))
 		})
 
 	})
diff --git a/pkg/configuration/configuration.go b/pkg/configuration/configuration.go
new file mode 100644
index 00000000..ff7bc10d
--- /dev/null
+++ b/pkg/configuration/configuration.go
@@ -0,0 +1,98 @@
+package configuration
+
+import (
+	"errors"
+	"time"
+)
+
+// NewConfiguration returns a new configuration
+func NewConfiguration(settings ...Setting) Configuration {
+	config := Configuration{
+		AttributeOverrides: make(map[string]string),
+		macros:             make(map[string]MacroTemplate),
+	}
+	for _, set := range settings {
+		set(&config)
+	}
+	return config
+}
+
+// Configuration the configuration used when rendering a document
+type Configuration struct {
+	Filename            string
+	AttributeOverrides  map[string]string
+	LastUpdated         time.Time
+	IncludeHeaderFooter bool
+	CSS                 string
+	macros              map[string]MacroTemplate
+}
+
+// Clone return a clone of the current configuration
+func (c Configuration) Clone() Configuration {
+	return Configuration{
+		CSS:                 c.CSS,
+		AttributeOverrides:  c.AttributeOverrides,
+		Filename:            c.Filename,
+		IncludeHeaderFooter: c.IncludeHeaderFooter,
+		LastUpdated:         c.LastUpdated,
+	}
+}
+
+// MacroTemplate finds and returns a user macro function by specified name.
+func (c Configuration) MacroTemplate(name string) (MacroTemplate, error) {
+	macro, ok := c.macros[name]
+	if ok {
+		return macro, nil
+	}
+	return nil, errors.New("unknown user macro: " + name)
+}
+
+const (
+	// LastUpdatedFormat key to the time format for the `last updated` document attribute
+	LastUpdatedFormat string = "2006-01-02 15:04:05 -0700"
+)
+
+// Setting a setting to customize the configuration used during parsing and rendering of a document
+type Setting func(config *Configuration)
+
+// WithLastUpdated function to set the `last updated` option in the renderer context (default is `time.Now()`)
+func WithLastUpdated(value time.Time) Setting {
+	return func(config *Configuration) {
+		config.LastUpdated = value
+	}
+}
+
+// WithAttributes function to set the `attribute overrides`
+func WithAttributes(attrs map[string]string) Setting {
+	return func(config *Configuration) {
+		config.AttributeOverrides = attrs
+	}
+}
+
+// WithHeaderFooter function to set the `include header/footer` setting in the config
+func WithHeaderFooter(value bool) Setting {
+	return func(config *Configuration) {
+		config.IncludeHeaderFooter = value
+	}
+}
+
+// WithCSS function to set the `css` setting in the config
+func WithCSS(href string) Setting {
+	return func(config *Configuration) {
+		config.CSS = href
+	}
+}
+
+// WithFilename function to set the `filename` setting in the config
+func WithFilename(filename string) Setting {
+	return func(config *Configuration) {
+		config.Filename = filename
+	}
+}
+
+// WithMacro defines the given template to a user macro with the given name
+func WithMacroTemplate(name string, t MacroTemplate) Setting {
+	return func(config *Configuration) {
+		config.macros[name] = t
+	}
+}
diff --git a/pkg/configuration/macro_template.go b/pkg/configuration/macro_template.go
new file mode 100644
index 00000000..9ca4bf4f
--- /dev/null
+++ b/pkg/configuration/macro_template.go
@@ -0,0 +1,8 @@
+package configuration
+
+import "io"
+
+// MacroTemplate an interface of template for user macro.
+type MacroTemplate interface {
+	Execute(wr io.Writer, data interface{}) error
+}
diff --git a/pkg/parser/document_preprocessing.go b/pkg/parser/document_preprocessing.go
index 37f67a8d..7e446244 100644
--- a/pkg/parser/document_preprocessing.go
+++ b/pkg/parser/document_preprocessing.go
@@ -3,6 +3,7 @@ package parser
 import (
 	"io"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 	"github.com/davecgh/go-spew/spew"
 
@@ -16,19 +17,22 @@ type ContextKey string
 const LevelOffset ContextKey = "leveloffset"
 
 // ParseDraftDocument parses a document's content and applies the preprocessing directives (file inclusions)
-func ParseDraftDocument(filename string, r io.Reader, opts ...Option) (types.DraftDocument, error) {
-	opts = append(opts, Entrypoint("AsciidocDocument"))
-	return parseDraftDocument(filename, r, []levelOffset{}, opts...)
+func ParseDraftDocument(r io.Reader, config configuration.Configuration, options ...Option) (types.DraftDocument, error) {
+	options = append(options, Entrypoint("AsciidocDocument"))
+	return parseDraftDocument(r, []levelOffset{}, config, options...)
 }
 
-func parseDraftDocument(filename string, r io.Reader, levelOffsets []levelOffset, opts ...Option) (types.DraftDocument, error) {
-	d, err := ParseReader(filename, r, opts...)
+func parseDraftDocument(r io.Reader, levelOffsets []levelOffset, config configuration.Configuration, options ...Option) (types.DraftDocument, error) {
+	d, err := ParseReader(config.Filename, r, options...)
 	if err != nil {
 		return types.DraftDocument{}, err
 	}
 	doc := d.(types.DraftDocument)
-	attrs := types.DocumentAttributes{}
-	blocks, err := parseElements(filename, doc.Blocks, attrs, levelOffsets, opts...)
+	attrs := types.DocumentAttributesWithOverrides{
+		Content:   map[string]interface{}{},
+		Overrides: map[string]string{},
+	}
+	blocks, err := parseElements(doc.Blocks, attrs, levelOffsets, config, options...)
 	if err != nil {
 		return types.DraftDocument{}, err
 	}
@@ -41,25 +45,25 @@ func parseDraftDocument(filename string, r io.Reader, levelOffsets []levelOffset
 }
 
 // parseElements resolves the file inclusions if any is found in the given elements
-func parseElements(filename string, elements []interface{}, attrs types.DocumentAttributes, levelOffsets []levelOffset, opts ...Option) ([]interface{}, error) {
+func parseElements(elements []interface{}, attrs types.DocumentAttributesWithOverrides, levelOffsets []levelOffset, config configuration.Configuration, options ...Option) ([]interface{}, error) {
 	result := []interface{}{}
 	for _, e := range elements {
 		switch e := e.(type) {
 		case types.DocumentAttributeDeclaration:
-			attrs[e.Name] = e.Value
+			attrs.Add(e.Name, e.Value)
 			result = append(result, e)
 		case types.FileInclusion:
 			// read the file and include its content
-			embedded, err := parseFileToInclude(filename, e, attrs, levelOffsets, opts...)
+			embedded, err := parseFileToInclude(e, attrs, levelOffsets, config, options...)
 			if err != nil {
 				// do not fail, but instead report the error in the console
 				log.Errorf("failed to include file '%s': %v", e.Location, err)
 			}
 			result = append(result, embedded.Blocks...)
 		case types.DelimitedBlock:
-			elmts, err := parseElements(filename, e.Elements, attrs, levelOffsets,
+			elmts, err := parseElements(e.Elements, attrs, levelOffsets, config,
 				// use a new var to avoid overridding the current one which needs to stay as-is for the rest of the doc parsing
-				append(opts, Entrypoint("AsciidocDocumentWithinDelimitedBlock"))...)
+				append(options, Entrypoint("AsciidocDocumentWithinDelimitedBlock"))...)
 			if err != nil {
 				return nil, err
 			}
diff --git a/pkg/parser/document_processing.go b/pkg/parser/document_processing.go
index 3ac6ada0..4668e13a 100644
--- a/pkg/parser/document_processing.go
+++ b/pkg/parser/document_processing.go
@@ -3,35 +3,26 @@ package parser
 import (
 	"io"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 )
 
 // ParseDocument parses the content of the reader identitied by the filename
-func ParseDocument(filename string, r io.Reader, opts ...Option) (types.Document, error) {
-	draftDoc, err := ParseDraftDocument(filename, r, opts...)
+func ParseDocument(r io.Reader, config configuration.Configuration) (types.Document, error) {
+	draftDoc, err := ParseDraftDocument(r, config)
 	if err != nil {
 		return types.Document{}, err
 	}
-	attrs := types.DocumentAttributes{}
-	// add all predefined attributes
-	for k, v := range Predefined {
-		if v, ok := v.(string); ok {
-			attrs[k] = v
-		}
+	attrs := types.DocumentAttributesWithOverrides{
+		Content:   types.DocumentAttributes{},
+		Overrides: config.AttributeOverrides,
 	}
-
+	// add all predefined attributes
+	attrs.AddAll(Predefined)
 	// also, add all front-matter key/values
-	for k, v := range draftDoc.FrontMatter.Content {
-		if v, ok := v.(string); ok {
-			attrs[k] = v
-		}
-	}
-
+	attrs.AddAll(draftDoc.FrontMatter.Content)
 	// also, add all DocumentAttributeDeclaration at the top of the document
-	documentAttributes := draftDoc.DocumentAttributes()
-	for k, v := range documentAttributes {
-		attrs[k] = v
-	}
+	attrs.AddAll(draftDoc.DocumentAttributes())
 
 	// apply document attribute substitutions and re-parse paragraphs that were affected
 	blocks, _, err := applyDocumentAttributeSubstitutions(draftDoc.Blocks, attrs)
@@ -44,7 +35,7 @@ func ParseDocument(filename string, r io.Reader, opts ...Option) (types.Document
 	if err != nil {
 		return types.Document{}, err
 	}
-	// apply document attribute substitutions and re-parse paragraphs that were affected
+	// filter out blocks not needed in the final doc
 	blocks = filter(blocks.([]interface{}), allMatchers...)
 
 	// now, rearrange elements in a hierarchical manner
@@ -57,8 +48,6 @@ func ParseDocument(filename string, r io.Reader, opts ...Option) (types.Document
 		doc.Attributes[k] = v
 	}
 	// and add all remaining attributes, too
-	for k, v := range documentAttributes {
-		doc.Attributes[k] = v
-	}
+	doc.Attributes.AddAll(draftDoc.DocumentAttributes())
 	return doc, nil
 }
diff --git a/pkg/parser/document_processing_apply_substitutions.go b/pkg/parser/document_processing_apply_substitutions.go
index 13e7b33c..d3c267ac 100644
--- a/pkg/parser/document_processing_apply_substitutions.go
+++ b/pkg/parser/document_processing_apply_substitutions.go
@@ -11,7 +11,7 @@ import (
 // applyDocumentAttributeSubstitutions(elements applies the document attribute substitutions
 // and re-parse the paragraphs that were affected
 // nolint: gocyclo
-func applyDocumentAttributeSubstitutions(element interface{}, attrs types.DocumentAttributes) (interface{}, bool, error) {
+func applyDocumentAttributeSubstitutions(element interface{}, attrs types.DocumentAttributesWithOverrides) (interface{}, bool, error) {
 	// the document attributes, as they are resolved while processing the blocks
 	log.Debugf("applying document substitutions on block of type %T", element)
 	switch e := element.(type) {
@@ -33,13 +33,13 @@ func applyDocumentAttributeSubstitutions(element interface{}, attrs types.Docume
 		}
 		return elements, false, nil
 	case types.DocumentAttributeDeclaration:
-		attrs[e.Name] = e.Value
+		attrs.Add(e.Name, e.Value)
 		return e, false, nil
 	case types.DocumentAttributeReset:
-		delete(attrs, e.Name)
+		attrs.Delete(e.Name)
 		return e, false, nil
 	case types.DocumentAttributeSubstitution:
-		if value, ok := attrs[e.Name].(string); ok {
+		if value, ok := attrs.GetAsString(e.Name); ok {
 			return types.StringElement{
 				Content: value,
 			}, true, nil
diff --git a/pkg/parser/document_processing_apply_substitutions_test.go b/pkg/parser/document_processing_apply_substitutions_test.go
index 11b24dad..73c9ab60 100644
--- a/pkg/parser/document_processing_apply_substitutions_test.go
+++ b/pkg/parser/document_processing_apply_substitutions_test.go
@@ -27,8 +27,11 @@ var _ = Describe("document attribute subsititutions", func() {
 			},
 		}
 		// when
-		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-			"foo": "bar",
+		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+			Content: map[string]interface{}{
+				"foo": "bar",
+			},
+			Overrides: map[string]string{},
 		})
 		// then
 		Expect(err).To(Not(HaveOccurred()))
@@ -65,8 +68,11 @@ var _ = Describe("document attribute subsititutions", func() {
 			},
 		}
 		// when
-		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-			"foo": "bar",
+		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+			Content: map[string]interface{}{
+				"foo": "bar",
+			},
+			Overrides: map[string]string{},
 		})
 		// then
 		Expect(err).To(Not(HaveOccurred()))
@@ -106,8 +112,11 @@ var _ = Describe("document attribute subsititutions", func() {
 			},
 		}
 		// when
-		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-			"foo": "bar",
+		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+			Content: map[string]interface{}{
+				"foo": "bar",
+			},
+			Overrides: map[string]string{},
 		})
 		// then
 		Expect(err).To(Not(HaveOccurred()))
@@ -147,7 +156,11 @@ var _ = Describe("document attribute subsititutions", func() {
 			},
 		}
 		// when
-		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{})
+		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+			Content:   map[string]interface{}{},
+			Overrides: map[string]string{},
+		})
+
 		// then
 		Expect(err).To(Not(HaveOccurred()))
 		Expect(applied).To(BeFalse())
@@ -186,7 +199,11 @@ var _ = Describe("document attribute subsititutions", func() {
 			},
 		}
 		// when
-		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{})
+		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+			Content:   map[string]interface{}{},
+			Overrides: map[string]string{},
+		})
+
 		// then
 		Expect(err).To(Not(HaveOccurred()))
 		Expect(applied).To(BeFalse())
@@ -231,10 +248,15 @@ var _ = Describe("document attribute subsititutions", func() {
 			},
 		}
 		// when
-		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-			"scheme": "https",
-			"host":   "foo.bar",
+		result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+			Content: map[string]interface{}{
+				"foo":    "bar",
+				"scheme": "https",
+				"host":   "foo.bar",
+			},
+			Overrides: map[string]string{},
 		})
+
 		// then
 		Expect(err).To(Not(HaveOccurred()))
 		Expect(applied).To(BeTrue())
@@ -289,8 +311,11 @@ var _ = Describe("document attribute subsititutions", func() {
 				},
 			}
 			// when
-			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-				"foo": "bar",
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{},
 			})
 			// then
 			Expect(err).To(Not(HaveOccurred()))
@@ -335,8 +360,11 @@ var _ = Describe("document attribute subsititutions", func() {
 				},
 			}
 			// when
-			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-				"foo": "bar",
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{},
 			})
 			// then
 			Expect(err).To(Not(HaveOccurred()))
@@ -381,8 +409,11 @@ var _ = Describe("document attribute subsititutions", func() {
 				},
 			}
 			// when
-			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-				"foo": "bar",
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{},
 			})
 			// then
 			Expect(err).To(Not(HaveOccurred()))
@@ -430,8 +461,11 @@ var _ = Describe("document attribute subsititutions", func() {
 				},
 			}
 			// when
-			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-				"foo": "bar",
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{},
 			})
 			// then
 			Expect(err).To(Not(HaveOccurred()))
@@ -486,8 +520,11 @@ var _ = Describe("document attribute subsititutions", func() {
 				},
 			}
 			// when
-			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-				"foo": "bar",
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{},
 			})
 			// then
 			Expect(err).To(Not(HaveOccurred()))
@@ -535,8 +572,11 @@ var _ = Describe("document attribute subsititutions", func() {
 				},
 			}
 			// when
-			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributes{
-				"foo": "bar",
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{},
 			})
 			// then
 			Expect(err).To(Not(HaveOccurred()))
@@ -552,4 +592,65 @@ var _ = Describe("document attribute subsititutions", func() {
 			}))
 		})
 	})
+
+	Context("attribute overrides", func() {
+
+		It("should replace with new StringElement on first position", func() {
+			// given
+			elements := []interface{}{
+				types.DocumentAttributeDeclaration{
+					Name:  "foo",
+					Value: "foo",
+				},
+				types.DocumentAttributeReset{
+					Name: "foo",
+				},
+				types.Paragraph{
+					Attributes: types.ElementAttributes{},
+					Lines: [][]interface{}{
+						{
+							types.DocumentAttributeSubstitution{
+								Name: "foo",
+							},
+							types.StringElement{
+								Content: " and more content.",
+							},
+						},
+					},
+				},
+			}
+			// when
+			result, applied, err := applyDocumentAttributeSubstitutions(elements, types.DocumentAttributesWithOverrides{
+				Content: map[string]interface{}{
+					"foo": "bar",
+				},
+				Overrides: map[string]string{
+					"foo": "BAR",
+				},
+			})
+			// then
+			Expect(err).To(Not(HaveOccurred()))
+			Expect(applied).To(BeTrue())
+			Expect(result).To(Equal([]interface{}{ // at this stage, DocumentAttributeDeclaration and DocumentAttributeReset are still present
+				types.DocumentAttributeDeclaration{
+					Name:  "foo",
+					Value: "foo",
+				},
+				types.DocumentAttributeReset{
+					Name: "foo",
+				},
+				types.Paragraph{
+					Attributes: types.ElementAttributes{},
+					Lines: [][]interface{}{
+						{
+							types.StringElement{
+								Content: "BAR and more content.",
+							},
+						},
+					},
+				},
+			}))
+		})
+	})
+
 })
diff --git a/pkg/parser/file_inclusion.go b/pkg/parser/file_inclusion.go
index 2489f436..2f75ab8c 100644
--- a/pkg/parser/file_inclusion.go
+++ b/pkg/parser/file_inclusion.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 	"text/template"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 	"github.com/davecgh/go-spew/spew"
 	"github.com/pkg/errors"
@@ -55,33 +56,35 @@ func absoluteOffset(offset int) levelOffset {
 	}
 }
 
-func parseFileToInclude(filename string, incl types.FileInclusion, attrs types.DocumentAttributes, levelOffsets []levelOffset, opts ...Option) (types.DraftDocument, error) {
+func parseFileToInclude(incl types.FileInclusion, attrs types.DocumentAttributesWithOverrides, levelOffsets []levelOffset, config configuration.Configuration, options ...Option) (types.DraftDocument, error) {
 	path := incl.Location.Resolve(attrs).String()
-	currentDir := filepath.Dir(filename)
-	log.Debugf("parsing '%s' from '%s' (%s)", path, currentDir, filename)
-	log.Debugf("file inclusion attributes: %s", spew.Sdump(incl.Attributes))
+	currentDir := filepath.Dir(config.Filename)
+	if log.IsLevelEnabled(log.DebugLevel) {
+		log.Debugf("parsing '%s' from '%s' (%s)", path, currentDir, config.Filename)
+		log.Debugf("file inclusion attributes: %s", spew.Sdump(incl.Attributes))
+	}
 	f, absPath, done, err := open(filepath.Join(currentDir, path))
 	defer done()
 	if err != nil {
-		return invalidFileErrMsg(filename, path, incl.RawText, err)
+		return invalidFileErrMsg(config.Filename, path, incl.RawText, err)
 	}
 	content := bytes.NewBuffer(nil)
 	scanner := bufio.NewScanner(bufio.NewReader(f))
 	if lineRanges, ok := incl.LineRanges(); ok {
 		if err := readWithinLines(scanner, content, lineRanges); err != nil {
-			return invalidFileErrMsg(filename, path, incl.RawText, err)
+			return invalidFileErrMsg(config.Filename, path, incl.RawText, err)
 		}
 	} else if tagRanges, ok := incl.TagRanges(); ok {
 		if err := readWithinTags(path, scanner, content, tagRanges); err != nil {
-			return invalidFileErrMsg(filename, path, incl.RawText, err)
+			return invalidFileErrMsg(config.Filename, path, incl.RawText, err)
 		}
 	} else {
 		if err := readAll(scanner, content); err != nil {
-			return invalidFileErrMsg(filename, path, incl.RawText, err)
+			return invalidFileErrMsg(config.Filename, path, incl.RawText, err)
 		}
 	}
 	if err := scanner.Err(); err != nil {
-		msg, err2 := invalidFileErrMsg(filename, path, incl.RawText, err)
+		msg, err2 := invalidFileErrMsg(config.Filename, path, incl.RawText, err)
 		if err2 != nil {
 			return types.DraftDocument{}, err2
 		}
@@ -103,9 +106,11 @@ func parseFileToInclude(filename string, incl types.FileInclusion, attrs types.D
 	}
 	// use a simpler/different grammar for non-asciidoc files.
 	if !IsAsciidoc(absPath) {
-		opts = append(opts, Entrypoint("TextDocument"))
+		options = append(options, Entrypoint("TextDocument"))
 	}
-	return parseDraftDocument(absPath, content, levelOffsets, opts...)
+	inclConfig := config.Clone()
+	inclConfig.Filename = absPath
+	return parseDraftDocument(content, levelOffsets, config, options...)
 }
 
 func invalidFileErrMsg(filename, path, rawText string, err error) (types.DraftDocument, error) {
diff --git a/pkg/parser/file_inclusion_test.go b/pkg/parser/file_inclusion_test.go
index 70746dfd..b359952b 100644
--- a/pkg/parser/file_inclusion_test.go
+++ b/pkg/parser/file_inclusion_test.go
@@ -702,7 +702,7 @@ include::{includedir}/include.foo[]`
 
 		It("should include adoc file within fenced block", func() {
 			source := "```\n" +
-				"include::../../test/includes/chapter-a.adoc[]\n" +
+				"include::../../test/includes/parent-include.adoc[]\n" +
 				"```"
 			expected := types.DraftDocument{
 				Blocks: []interface{}{
@@ -715,7 +715,7 @@ include::{includedir}/include.foo[]`
 								Lines: [][]interface{}{
 									{
 										types.StringElement{
-											Content: "= Chapter A",
+											Content: "= parent title",
 										},
 									},
 								},
@@ -726,7 +726,84 @@ include::{includedir}/include.foo[]`
 								Lines: [][]interface{}{
 									{
 										types.StringElement{
-											Content: "content",
+											Content: "first line of parent",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "= child title",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "first line of child",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "== grandchild title",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "first line of grandchild",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "last line of grandchild",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "last line of child",
+										},
+									},
+								},
+							},
+							types.BlankLine{},
+							types.Paragraph{
+								Attributes: types.ElementAttributes{},
+								Lines: [][]interface{}{
+									{
+										types.StringElement{
+											Content: "last line of parent",
 										},
 									},
 								},
diff --git a/pkg/renderer/context.go b/pkg/renderer/context.go
index 05df716d..f66c02d4 100644
--- a/pkg/renderer/context.go
+++ b/pkg/renderer/context.go
@@ -1,62 +1,48 @@
 package renderer
 
 import (
-	"errors"
-	"io"
-
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
+
 	log "github.com/sirupsen/logrus"
 )
 
-// MacroTemplate an interface of template for user macro.
-type MacroTemplate interface {
-	Execute(wr io.Writer, data interface{}) error
-}
-
 // Context is a custom implementation of the standard golang context.Context interface,
 // which carries the types.Document which is being processed
 type Context struct {
 	Document types.Document
+	Config   configuration.Configuration
 	// TableOfContents exists even if the document did not specify the `:toc:` attribute.
 	// It will take into account the configured `:toclevels:` attribute value.
 	TableOfContents types.TableOfContents
-	options         map[string]interface{}
-	macros          map[string]MacroTemplate
+	// macros               map[string]MacroTemplate
+	includeBlankLine     bool
+	withinDelimitedBlock bool
+	withinList           int
+	counters             map[string]int
 }
 
 // NewContext returns a new rendering context for the given document.
-func NewContext(document types.Document, options ...Option) Context {
-	result := Context{
+func NewContext(document types.Document, config configuration.Configuration) Context {
+	return Context{
 		Document: document,
-		options:  make(map[string]interface{}),
-		macros:   make(map[string]MacroTemplate),
+		Config:   config,
+		counters: make(map[string]int),
+		// macros:   make(map[string]MacroTemplate),
 	}
-	for _, option := range options {
-		option(&result)
-	}
-	return result
 }
 
-const includeBlankLine string = "includeBlankLine"
-
 // SetIncludeBlankLine sets the rendering context to include (or not) the blank lines
 func (ctx *Context) SetIncludeBlankLine(b bool) bool {
-	var oldvalue bool
-	if v, ok := ctx.options[includeBlankLine].(bool); ok {
-		oldvalue = v
-	}
-	ctx.options[includeBlankLine] = b
-	log.Debugf("set '%s' context param to '%t' (was '%t' before)", includeBlankLine, b, oldvalue)
+	oldvalue := ctx.includeBlankLine
+	ctx.includeBlankLine = b
+	log.Debugf("set 'includeBlankLine' context param to '%t' (was '%t' before)", b, oldvalue)
 	return oldvalue
 }
 
 // IncludeBlankLine indicates if blank lines should be rendered (default false)
 func (ctx *Context) IncludeBlankLine() bool {
-	if b, found := ctx.options[includeBlankLine].(bool); found {
-		return b
-	}
-	// by default, ignore blank lines
-	return false
+	return ctx.includeBlankLine
 }
 
 const withinDelimitedBlock string = "withinDelimitedBlock"
@@ -64,58 +50,31 @@ const withinDelimitedBlock string = "withinDelimitedBlock"
 // SetWithinDelimitedBlock sets the rendering context to be within a delimited block
 func (ctx *Context) SetWithinDelimitedBlock(b bool) bool {
 	log.Debugf("set rendering elements within a delimited block to `%t`", b)
-	var oldvalue bool
-	if v, ok := ctx.options[withinDelimitedBlock].(bool); ok {
-		oldvalue = v
-	}
+	oldvalue := ctx.withinDelimitedBlock
 	log.Debugf("set '%s' context param to '%t' (was '%t' before)", withinDelimitedBlock, b, oldvalue)
-	ctx.options[withinDelimitedBlock] = b
+	ctx.withinDelimitedBlock = b
 	return oldvalue
 }
 
 // WithinDelimitedBlock indicates if the current element to render is within a delimited block or not
 func (ctx *Context) WithinDelimitedBlock() bool {
-	if b, found := ctx.options[withinDelimitedBlock].(bool); found {
-		log.Debugf("rendering elements within a delimited block? %t", b)
-		return b
-	}
-	// by default, consider not within a block
-	return false
+	return ctx.withinDelimitedBlock
 }
 
 const withinList string = "withinList"
 
 // SetWithinList sets the rendering context to be within a list or a nest list
 func (ctx *Context) SetWithinList(w bool) {
-	// log.Debugf("set rendering elements within a list to `%t`", w)
-	var counter int
-	var ok bool
-	if counter, ok = ctx.options[withinList].(int); ok {
-		// keep track of the depth of the list
-		if w {
-			counter++
-		} else {
-			counter--
-		}
+	if w {
+		ctx.withinList++
 	} else {
-		if w {
-			counter = 1
-		} else {
-			counter = 0
-		}
+		ctx.withinList--
 	}
-	// update the counter in the context
-	ctx.options[withinList] = counter
 }
 
 // WithinList indicates if the current element to render is within a list or not
 func (ctx *Context) WithinList() bool {
-	if counter, found := ctx.options[withinList].(int); found {
-		// log.Debugf("rendering elements within a list? %t (%d)", (counter > 0), counter)
-		return counter > 0
-	}
-	// by default, ignore blank lines
-	return false
+	return ctx.withinList > 0
 }
 
 const tableCounter = "tableCounter"
@@ -140,24 +99,87 @@ func (ctx *Context) GetAndIncrementExampleBlockCounter() int {
 }
 
 // getAndIncrementCounter returns the current value for the  counter after internally incrementing it.
-func (ctx *Context) getAndIncrementCounter(counter string) int {
-	if _, found := ctx.options[counter]; !found {
-		ctx.options[counter] = 1
+func (ctx *Context) getAndIncrementCounter(name string) int {
+	if _, found := ctx.counters[name]; !found {
+		ctx.counters[name] = 1
+		return 1
 	}
-	if c, ok := ctx.options[counter].(int); ok {
-		ctx.options[counter] = c + 1
-		return c
-	}
-	ctx.options[counter] = 1
-	log.Warnf("'%s' counter was set to a non-int value", counter)
-	return 1
+	ctx.counters[name]++
+	return ctx.counters[name]
 }
 
-// MacroTemplate finds and returns a user macro function by specified name.
-func (ctx *Context) MacroTemplate(name string) (MacroTemplate, error) {
-	macro, ok := ctx.macros[name]
-	if ok {
-		return macro, nil
-	}
-	return nil, errors.New("unknown user macro: " + name)
-}
+// //Option the options when rendering a document
+// type Option func(ctx *Context)
+
+// const (
+// 	// keyLastUpdated the key to specify the last update of the document to render.
+// 	// Can be a string or a time, which will be formatted using the 2006/01/02 15:04:05 MST` pattern
+// 	keyLastUpdated string = types.AttrLastUpdated
+// 	// keyIncludeHeaderFooter key to a bool value to indicate if the header and footer should be rendered
+// 	keyIncludeHeaderFooter string = "IncludeHeaderFooter"
+// 	// keyCSS key to the options CSS to add in the document head. Default is empty ("")
+// 	keyCSS string = "CSS"
+// 	// keyEntrypoint key to the entrypoint to start with when parsing the document
+// 	keyEntrypoint string = "Entrypoint"
+// 	// LastUpdatedFormat key to the time format for the `last updated` document attribute
+// 	LastUpdatedFormat string = "2006-01-02 15:04:05 -0700"
+// )
+
+// // LastUpdated function to set the `last updated` option in the renderer context (default is `time.Now()`)
+// func WithLastUpdated(value time.Time) Option {
+// 	return func(ctx *Context) {
+// 		ctx.options[keyLastUpdated] = value
+// 	}
+// }
+
+// // IncludeHeaderFooter function to set the `include header/footer` option in the renderer context
+// func WithHeaderFooter(value bool) Option {
+// 	return func(ctx *Context) {
+// 		ctx.options[keyIncludeHeaderFooter] = value
+// 	}
+// }
+
+// // IncludeCSS function to set the `css` option in the renderer context
+// func WithCSS(href string) Option {
+// 	return func(ctx *Context) {
+// 		ctx.options[keyCSS] = href
+// 	}
+// }
+
+// // Entrypoint function to set the `entrypoint` option in the renderer context
+// func Entrypoint(entrypoint string) Option {
+// 	return func(ctx *Context) {
+// 		ctx.options[keyEntrypoint] = entrypoint
+// 	}
+// }
+
+// // DefineMacro defines the given template to a user macro with the given name
+// func WithMacroTemplate(name string, t MacroTemplate) Option {
+// 	return func(ctx *Context) {
+// 		ctx.macros[name] = t
+// 	}
+// }
+
+// // LastUpdated returns the value of the 'LastUpdated' Option if it was present,
+// // otherwise it returns the current time using the `2006/01/02 15:04:05 MST` format
+// func (ctx *Context) WithLastUpdated() string {
+// 	if lastUpdated, ok := ctx.options[keyLastUpdated].(time.Time); ok {
+// 		return lastUpdated.Format(LastUpdatedFormat)
+// 	}
+// 	return time.Now().Format(LastUpdatedFormat)
+// }
+
+// IncludeHeaderFooter returns the value of the 'IncludeHeaderFooter' Option if it was present,
+// otherwise it returns `false`
+// func (ctx *Context) WithHeaderFooter() bool {
+// 	return ctx.IncludeHeaderFooter
+// }
+
+// // CSS returns the value of the 'CSS' Option if it was present,
+// // otherwise it returns an empty string
+// func (ctx *Context) CSS() string {
+// 	if css, ok := ctx.options[keyCSS].(string); ok {
+// 		return css
+// 	}
+// 	return ""
+// }
diff --git a/pkg/renderer/html5/article_adoc_test.go b/pkg/renderer/html5/article_adoc_test.go
index 57a74f44..5a2ecf26 100644
--- a/pkg/renderer/html5/article_adoc_test.go
+++ b/pkg/renderer/html5/article_adoc_test.go
@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"os"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/parser"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer/html5"
@@ -20,11 +21,12 @@ var _ = Describe("article.adoc", func() {
 		f, err := os.Open("article.adoc")
 		Expect(err).ToNot(HaveOccurred())
 		reader := bufio.NewReader(f)
-		doc, err := parser.ParseDocument("", reader)
+		config := configuration.NewConfiguration()
+		doc, err := parser.ParseDocument(reader, config)
 		Expect(err).ToNot(HaveOccurred())
 		GinkgoT().Logf("actual document: `%s`", spew.Sdump(doc))
 		buff := bytes.NewBuffer(nil)
-		ctx := renderer.NewContext(doc)
+		ctx := renderer.NewContext(doc, config)
 		_, err = html5.Render(ctx, buff)
 		Expect(err).ToNot(HaveOccurred())
 	})
diff --git a/pkg/renderer/html5/document_details.go b/pkg/renderer/html5/document_details.go
index 8865a621..9cc2bdb7 100644
--- a/pkg/renderer/html5/document_details.go
+++ b/pkg/renderer/html5/document_details.go
@@ -7,6 +7,7 @@ import (
 	texttemplate "text/template"
 
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/types"
 	"github.com/pkg/errors"
 	log "github.com/sirupsen/logrus"
 )
@@ -27,7 +28,7 @@ func init() {
 }
 
 func renderDocumentDetails(ctx renderer.Context) (*htmltemplate.HTML, error) {
-	if ctx.Document.Attributes.HasAuthors() {
+	if ctx.Document.Attributes.Has(types.AttrAuthor) {
 		authors, err := renderDocumentAuthorsDetails(ctx)
 		if err != nil {
 			return nil, errors.Wrap(err, "error while rendering the document details")
diff --git a/pkg/renderer/html5/document_details_test.go b/pkg/renderer/html5/document_details_test.go
index 5f82e5eb..2e7cc7a6 100644
--- a/pkg/renderer/html5/document_details_test.go
+++ b/pkg/renderer/html5/document_details_test.go
@@ -3,7 +3,7 @@ package html5_test
 import (
 	"time"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	. "github.com/bytesparadise/libasciidoc/testsupport"
 
 	. "github.com/onsi/ginkgo"
@@ -52,8 +52,7 @@ Last updated {{.LastUpdated}}
 </body>
 </html>`
 			now := time.Now()
-			Expect(RenderHTML5Body(source, renderer.IncludeHeaderFooter(true), renderer.LastUpdated(time.Now()))).
-				To(MatchHTML5Template(expected, now))
+			Expect(RenderHTML5Body(source, configuration.WithHeaderFooter(true), configuration.WithLastUpdated(time.Now()))).To(MatchHTML5Template(expected, now))
 		})
 
 		It("header with 2 authors and no revision", func() {
@@ -91,9 +90,8 @@ Last updated {{.LastUpdated}}
 </body>
 </html>`
 			now := time.Now()
-			Expect(RenderHTML5Body(source, renderer.IncludeHeaderFooter(true), renderer.LastUpdated(now))).
+			Expect(RenderHTML5Body(source, configuration.WithHeaderFooter(true), configuration.WithLastUpdated(time.Now()))).
 				To(MatchHTML5Template(expected, now))
-
 		})
 	})
 })
diff --git a/pkg/renderer/html5/elements.go b/pkg/renderer/html5/elements.go
index 9dbf52b9..dddf672e 100644
--- a/pkg/renderer/html5/elements.go
+++ b/pkg/renderer/html5/elements.go
@@ -15,7 +15,7 @@ func renderElements(ctx renderer.Context, elements []interface{}) ([]byte, error
 	log.Debugf("rendering %d elements(s)...", len(elements))
 	buff := bytes.NewBuffer(nil)
 	hasContent := false
-	if !ctx.IncludeHeaderFooter() && len(elements) > 0 {
+	if !ctx.Config.IncludeHeaderFooter && len(elements) > 0 {
 		if s, ok := elements[0].(types.Section); ok && s.Level == 0 {
 			// don't render the top-level section, but only its elements (plus the rest if there's anything)
 			if len(elements) > 1 {
diff --git a/pkg/renderer/html5/file_inclusion_test.go b/pkg/renderer/html5/file_inclusion_test.go
index 1771b116..bbd02211 100644
--- a/pkg/renderer/html5/file_inclusion_test.go
+++ b/pkg/renderer/html5/file_inclusion_test.go
@@ -3,7 +3,7 @@ package html5_test
 import (
 	"time"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 	. "github.com/bytesparadise/libasciidoc/testsupport"
 
@@ -30,10 +30,10 @@ var _ = Describe("file inclusions", func() {
 </div>
 </div>
 </div>`
-		Expect(RenderHTML5Body(source, WithFilename("test.adoc"), renderer.LastUpdated(lastUpdated))).To(Equal(expected))
+		Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"), configuration.WithLastUpdated(lastUpdated))).To(Equal(expected))
 		Expect(DocumentMetadata(source, lastUpdated)).To(Equal(types.Metadata{
 			Title:       "",
-			LastUpdated: lastUpdated.Format(renderer.LastUpdatedFormat),
+			LastUpdated: lastUpdated.Format(configuration.LastUpdatedFormat),
 			TableOfContents: types.TableOfContents{
 				Sections: []types.ToCSection{
 					{
@@ -64,7 +64,7 @@ var _ = Describe("file inclusions", func() {
 </div>
 </div>
 </div>`
-		Expect(RenderHTML5Body(source, WithFilename("tmp/foo.adoc"))).To(Equal(expected))
+		Expect(RenderHTML5Body(source, configuration.WithFilename("tmp/foo.adoc"))).To(Equal(expected))
 		// verify no error/warning in logs
 		Expect(console).ToNot(ContainAnyMessageWithLevels(log.ErrorLevel, log.WarnLevel))
 	})
@@ -80,7 +80,7 @@ var _ = Describe("file inclusions", func() {
 <p>last line of grandchild</p>
 </div>
 </div>`
-		Expect(RenderHTML5Body(source, WithFilename("test.adoc"))).To(Equal(expected))
+		Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 	})
 
 	It("should include grandchild content with absolute offset", func() {
@@ -96,7 +96,7 @@ var _ = Describe("file inclusions", func() {
 </div>
 </div>
 </div>`
-		Expect(RenderHTML5Body(source, WithFilename("test.adoc"))).To(Equal(expected))
+		Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 	})
 
 	It("should include child and grandchild content with relative level offset", func() {
@@ -136,7 +136,7 @@ var _ = Describe("file inclusions", func() {
 </div>
 </div>
 </div>`
-		Expect(RenderHTML5Body(source, WithFilename("test.adoc"))).To(Equal(expected))
+		Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 	})
 
 	It("should include child and grandchild content with relative then absolute level offset", func() {
@@ -176,7 +176,7 @@ var _ = Describe("file inclusions", func() {
 </div>
 </div>
 </div>`
-		Expect(RenderHTML5Body(source, WithFilename("test.adoc"))).To(Equal(expected))
+		Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 	})
 
 	It("include adoc file with leveloffset attribute", func() {
@@ -933,7 +933,7 @@ last line of grandchild</pre>
 				expected := `<div class="paragraph">
 <p>Unresolved directive in test.adoc - include::../../../test/includes/unknown.adoc[leveloffset=+1]</p>
 </div>`
-				Expect(RenderHTML5Body(source)).To(Equal(expected))
+				Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 				// verify error in logs
 				Expect(console).To(
 					ContainMessageWithLevel(
@@ -951,7 +951,7 @@ last line of grandchild</pre>
 				expected := `<div class="paragraph">
 <p>Unresolved directive in test.adoc - include::{includedir}/unknown.adoc[leveloffset=+1]</p>
 </div>`
-				Expect(RenderHTML5Body(source)).To(Equal(expected))
+				Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 				// verify error in logs
 				Expect(console).To(
 					ContainMessageWithLevel(
@@ -976,7 +976,7 @@ include::../../../test/includes/unknown.adoc[leveloffset=+1]
 <pre>Unresolved directive in test.adoc - include::../../../test/includes/unknown.adoc[leveloffset=+1]</pre>
 </div>
 </div>`
-				Expect(RenderHTML5Body(source)).To(Equal(expected))
+				Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 				// verify error in logs
 				Expect(console).To(
 					ContainMessageWithLevel(
@@ -998,7 +998,7 @@ include::{includedir}/unknown.adoc[leveloffset=+1]
 <pre>Unresolved directive in test.adoc - include::{includedir}/unknown.adoc[leveloffset=+1]</pre>
 </div>
 </div>`
-				Expect(RenderHTML5Body(source)).To(Equal(expected))
+				Expect(RenderHTML5Body(source, configuration.WithFilename("test.adoc"))).To(Equal(expected))
 				// verify error in logs
 				Expect(console).To(
 					ContainMessageWithLevel(
diff --git a/pkg/renderer/html5/html5.go b/pkg/renderer/html5/html5.go
index 7cbcf340..3536b376 100644
--- a/pkg/renderer/html5/html5.go
+++ b/pkg/renderer/html5/html5.go
@@ -5,6 +5,7 @@ import (
 	"io"
 	texttemplate "text/template"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 
@@ -62,7 +63,7 @@ func Render(ctx renderer.Context, output io.Writer) (types.Metadata, error) {
 	if err != nil {
 		return types.Metadata{}, errors.Wrapf(err, "unable to render full document")
 	}
-	if ctx.IncludeHeaderFooter() {
+	if ctx.Config.IncludeHeaderFooter {
 		log.Debugf("Rendering full document...")
 		// use a temporary writer for the document's content
 		renderedElements, err := renderDocumentElements(ctx)
@@ -89,8 +90,8 @@ func Render(ctx renderer.Context, output io.Writer) (types.Metadata, error) {
 			Header:      string(renderedHeader),
 			Content:     htmltemplate.HTML(string(renderedElements)), //nolint: gosec
 			RevNumber:   revNumber,
-			LastUpdated: ctx.LastUpdated(),
-			CSS:         ctx.CSS(),
+			LastUpdated: ctx.Config.LastUpdated.Format(configuration.LastUpdatedFormat),
+			CSS:         ctx.Config.CSS,
 			Details:     documentDetails,
 		})
 		if err != nil {
@@ -110,7 +111,7 @@ func Render(ctx renderer.Context, output io.Writer) (types.Metadata, error) {
 	// generate the metadata to be returned to the caller
 	metadata := types.Metadata{}
 	metadata.Title = string(renderedTitle)
-	metadata.LastUpdated = ctx.LastUpdated()
+	metadata.LastUpdated = ctx.Config.LastUpdated.Format(configuration.LastUpdatedFormat)
 	// include a version of the table of contents
 	metadata.TableOfContents = ctx.TableOfContents
 	return metadata, err
diff --git a/pkg/renderer/html5/html5_test.go b/pkg/renderer/html5/html5_test.go
index 4d5beaf1..4a6120ec 100644
--- a/pkg/renderer/html5/html5_test.go
+++ b/pkg/renderer/html5/html5_test.go
@@ -3,7 +3,7 @@ package html5_test
 import (
 	"time"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	. "github.com/bytesparadise/libasciidoc/testsupport"
 
 	. "github.com/onsi/ginkgo"
@@ -41,9 +41,9 @@ Last updated {{.LastUpdated}}
 </body>
 </html>`
 			now := time.Now()
-			Expect(RenderHTML5Body(source, renderer.IncludeHeaderFooter(true),
-				renderer.IncludeCSS("/path/to/style.css"),
-				renderer.LastUpdated(now))).
+			Expect(RenderHTML5Body(source, configuration.WithHeaderFooter(true),
+				configuration.WithCSS("/path/to/style.css"),
+				configuration.WithLastUpdated(now))).
 				To(MatchHTML5Template(expected, now))
 		})
 	})
diff --git a/pkg/renderer/html5/inline_elements.go b/pkg/renderer/html5/inline_elements.go
index 308a7b35..9287eeed 100644
--- a/pkg/renderer/html5/inline_elements.go
+++ b/pkg/renderer/html5/inline_elements.go
@@ -24,16 +24,16 @@ func verbatim() renderLinesOption {
 
 func renderInlineElements(ctx renderer.Context, elements []interface{}, options ...renderLinesOption) ([]byte, error) {
 	log.Debugf("rendering line with %d element(s)...", len(elements))
-	config := renderLinesConfig{
+	linesRenderer := renderLinesConfig{
 		render: renderElement,
 	}
 	for _, apply := range options {
-		apply(&config)
+		apply(&linesRenderer)
 	}
 	// first pass or rendering, using the provided `renderElementFunc`:
 	buf := bytes.NewBuffer(nil)
 	for i, element := range elements {
-		renderedElement, err := config.render(ctx, element)
+		renderedElement, err := linesRenderer.render(ctx, element)
 		if err != nil {
 			return nil, errors.Wrapf(err, "unable to render line")
 		}
diff --git a/pkg/renderer/html5/paragraph.go b/pkg/renderer/html5/paragraph.go
index b8857dd5..c6d4a95f 100644
--- a/pkg/renderer/html5/paragraph.go
+++ b/pkg/renderer/html5/paragraph.go
@@ -344,16 +344,16 @@ func PlainText() RenderLinesOption {
 // and includes an `\n` character in-between, until the last one.
 // Trailing spaces are removed for each line.
 func renderLines(ctx renderer.Context, lines [][]interface{}, options ...RenderLinesOption) ([]byte, error) { // renderLineFunc renderFunc, hardbreak bool
-	config := RenderLinesConfig{
+	linesRenderer := RenderLinesConfig{
 		render:     renderLine,
 		hardbreaks: false,
 	}
 	for _, apply := range options {
-		apply(&config)
+		apply(&linesRenderer)
 	}
 	buf := bytes.NewBuffer(nil)
 	for i, e := range lines {
-		renderedElement, err := config.render(ctx, e)
+		renderedElement, err := linesRenderer.render(ctx, e)
 		if err != nil {
 			return nil, errors.Wrap(err, "unable to render lines")
 		}
@@ -367,7 +367,7 @@ func renderLines(ctx renderer.Context, lines [][]interface{}, options ...RenderL
 		if i < len(lines)-1 && (len(renderedElement) > 0 || ctx.WithinDelimitedBlock()) {
 			// log.Debugf("rendered line is not the last one in the slice")
 			var err error
-			if config.hardbreaks {
+			if linesRenderer.hardbreaks {
 				_, err = buf.WriteString("<br>\n")
 			} else {
 				_, err = buf.WriteString("\n")
diff --git a/pkg/renderer/html5/user_macro.go b/pkg/renderer/html5/user_macro.go
index d0b5916c..6717c308 100644
--- a/pkg/renderer/html5/user_macro.go
+++ b/pkg/renderer/html5/user_macro.go
@@ -9,7 +9,7 @@ import (
 
 func renderUserMacro(ctx renderer.Context, um types.UserMacro) ([]byte, error) {
 	buf := bytes.NewBuffer([]byte{})
-	macro, err := ctx.MacroTemplate(um.Name)
+	macro, err := ctx.Config.MacroTemplate(um.Name)
 	if err != nil {
 		if um.Kind == types.BlockMacro {
 			// fallback to paragraph
diff --git a/pkg/renderer/html5/user_macro_test.go b/pkg/renderer/html5/user_macro_test.go
index 99cf7766..cda96555 100644
--- a/pkg/renderer/html5/user_macro_test.go
+++ b/pkg/renderer/html5/user_macro_test.go
@@ -3,7 +3,7 @@ package html5_test
 import (
 	texttemplate "text/template"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer/html5"
 	. "github.com/bytesparadise/libasciidoc/testsupport"
 
@@ -34,7 +34,7 @@ var _ = Describe("user macros", func() {
 <span>hello world</span>
 </div>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("user macro block with attribute", func() {
@@ -45,7 +45,7 @@ var _ = Describe("user macros", func() {
 <span>hello world!!!!</span>
 </div>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("user macro block with value", func() {
@@ -56,7 +56,7 @@ var _ = Describe("user macros", func() {
 <span>hello JohnDoe</span>
 </div>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("user macro block with value and attributes", func() {
@@ -67,7 +67,7 @@ var _ = Describe("user macros", func() {
 <span>Hi JohnDoe!!</span>
 </div>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("undefined inline macro", func() {
@@ -85,7 +85,7 @@ var _ = Describe("user macros", func() {
 			expected := `<div class="paragraph">
 <p>AAA <span>hello world</span></p>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("inline macro with attribute", func() {
@@ -94,7 +94,7 @@ var _ = Describe("user macros", func() {
 			expected := `<div class="paragraph">
 <p>AAA <span>hello world!!!!!</span></p>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("inline macro with value", func() {
@@ -103,7 +103,7 @@ var _ = Describe("user macros", func() {
 			expected := `<div class="paragraph">
 <p>AAA <span>hello JohnDoe</span></p>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 		It("inline macro with value and attributes", func() {
@@ -112,7 +112,7 @@ var _ = Describe("user macros", func() {
 			expected := `<div class="paragraph">
 <p>AAA <span>Hi JohnDoe!!</span></p>
 </div>`
-			Expect(RenderHTML5Body(source, renderer.DefineMacro(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
+			Expect(RenderHTML5Body(source, configuration.WithMacroTemplate(helloMacroTmpl.Name(), helloMacroTmpl))).To(Equal(expected))
 		})
 
 	})
diff --git a/pkg/renderer/options.go b/pkg/renderer/options.go
deleted file mode 100644
index 41c12d61..00000000
--- a/pkg/renderer/options.go
+++ /dev/null
@@ -1,86 +0,0 @@
-package renderer
-
-import (
-	"time"
-
-	"github.com/bytesparadise/libasciidoc/pkg/types"
-)
-
-//Option the options when rendering a document
-type Option func(ctx *Context)
-
-const (
-	// keyLastUpdated the key to specify the last update of the document to render.
-	// Can be a string or a time, which will be formatted using the 2006/01/02 15:04:05 MST` pattern
-	keyLastUpdated string = types.AttrLastUpdated
-	// keyIncludeHeaderFooter key to a bool value to indicate if the header and footer should be rendered
-	keyIncludeHeaderFooter string = "IncludeHeaderFooter"
-	// keyCSS key to the options CSS to add in the document head. Default is empty ("")
-	keyCSS string = "CSS"
-	// keyEntrypoint key to the entrypoint to start with when parsing the document
-	keyEntrypoint string = "Entrypoint"
-	// LastUpdatedFormat key to the time format for the `last updated` document attribute
-	LastUpdatedFormat string = "2006-01-02 15:04:05 -0700"
-)
-
-// LastUpdated function to set the `last updated` option in the renderer context (default is `time.Now()`)
-func LastUpdated(value time.Time) Option {
-	return func(ctx *Context) {
-		ctx.options[keyLastUpdated] = value
-	}
-}
-
-// IncludeHeaderFooter function to set the `include header/footer` option in the renderer context
-func IncludeHeaderFooter(value bool) Option {
-	return func(ctx *Context) {
-		ctx.options[keyIncludeHeaderFooter] = value
-	}
-}
-
-// IncludeCSS function to set the `css` option in the renderer context
-func IncludeCSS(href string) Option {
-	return func(ctx *Context) {
-		ctx.options[keyCSS] = href
-	}
-}
-
-// Entrypoint function to set the `entrypoint` option in the renderer context
-func Entrypoint(entrypoint string) Option {
-	return func(ctx *Context) {
-		ctx.options[keyEntrypoint] = entrypoint
-	}
-}
-
-// DefineMacro defines the given template to a user macro with the given name
-func DefineMacro(name string, t MacroTemplate) Option {
-	return func(ctx *Context) {
-		ctx.macros[name] = t
-	}
-}
-
-// LastUpdated returns the value of the 'LastUpdated' Option if it was present,
-// otherwise it returns the current time using the `2006/01/02 15:04:05 MST` format
-func (ctx *Context) LastUpdated() string {
-	if lastUpdated, ok := ctx.options[keyLastUpdated].(time.Time); ok {
-		return lastUpdated.Format(LastUpdatedFormat)
-	}
-	return time.Now().Format(LastUpdatedFormat)
-}
-
-// IncludeHeaderFooter returns the value of the 'IncludeHeaderFooter' Option if it was present,
-// otherwise it returns `false`
-func (ctx *Context) IncludeHeaderFooter() bool {
-	if includeHeaderFooter, ok := ctx.options[keyIncludeHeaderFooter].(bool); ok {
-		return includeHeaderFooter
-	}
-	return false
-}
-
-// CSS returns the value of the 'CSS' Option if it was present,
-// otherwise it returns an empty string
-func (ctx *Context) CSS() string {
-	if css, ok := ctx.options[keyCSS].(string); ok {
-		return css
-	}
-	return ""
-}
diff --git a/pkg/types/document_attributes.go b/pkg/types/document_attributes.go
index ea2f2511..6762f276 100644
--- a/pkg/types/document_attributes.go
+++ b/pkg/types/document_attributes.go
@@ -1,9 +1,5 @@
 package types
 
-import (
-	"reflect"
-)
-
 // DocumentAttributes the document attributes
 type DocumentAttributes map[string]interface{}
 
@@ -13,38 +9,17 @@ func (a DocumentAttributes) Has(key string) bool {
 	return ok
 }
 
-// HasAuthors returns `true` if the document has one or more authors, `false` otherwise.
-func (a DocumentAttributes) HasAuthors() bool {
-	_, exists := a["author"]
-	return exists
-}
-
 // AddAll adds the given attributes
-func (a DocumentAttributes) AddAll(attrs map[string]interface{}) DocumentAttributes {
+func (a DocumentAttributes) AddAll(attrs map[string]interface{}) {
 	for k, v := range attrs {
 		a.Add(k, v)
 	}
-	return a
 }
 
 // Add adds the given attribute if its value is non-nil
 // TODO: raise a warning if there was already a name/value
-func (a DocumentAttributes) Add(key string, value interface{}) DocumentAttributes {
-	// do not add nil or empty values
-	if value == nil {
-		return a
-	}
-	v := reflect.ValueOf(value)
-	k := v.Kind()
-	// if the argument is a pointer, then retrieve the value it points to
-	if k == reflect.Ptr {
-		if v.Elem().IsValid() {
-			a[key] = v.Elem().Interface()
-		}
-	} else {
-		a[key] = value
-	}
-	return a
+func (a DocumentAttributes) Add(key string, value interface{}) {
+	a[key] = value
 }
 
 // AddNonEmpty adds the given attribute if its value is non-nil and non-empty
@@ -63,8 +38,8 @@ func (a DocumentAttributes) AddDeclaration(attr DocumentAttributeDeclaration) {
 	a.Add(attr.Name, attr.Value)
 }
 
-// Reset resets the given attribute
-func (a DocumentAttributes) Reset(attr DocumentAttributeReset) {
+// Delete deletes the given attribute
+func (a DocumentAttributes) Delete(attr DocumentAttributeReset) {
 	delete(a, attr.Name)
 }
 
@@ -91,3 +66,57 @@ func (a DocumentAttributes) GetAsStringWithDefault(key, defaultValue string) str
 	}
 	return defaultValue
 }
+
+// DocumentAttributesWithOverrides the document attributes with some overrides provided by the CLI (for example)
+type DocumentAttributesWithOverrides struct {
+	Content   map[string]interface{}
+	Overrides map[string]string
+}
+
+// Add add the given attribute
+func (a DocumentAttributesWithOverrides) Add(key string, value interface{}) {
+	a.Content[key] = value
+}
+
+// AddAll adds the given attributes
+func (a DocumentAttributesWithOverrides) AddAll(attrs map[string]interface{}) {
+	for k, v := range attrs {
+		a.Content[k] = v
+	}
+}
+
+// Delete deletes the given attribute
+func (a DocumentAttributesWithOverrides) Delete(key string) {
+	delete(a.Content, key)
+}
+
+// GetAsString gets the string value for the given key (+ `true`),
+// or empty string (+ `false`) if none was found
+func (a DocumentAttributesWithOverrides) GetAsString(key string) (string, bool) {
+	// if value is overridden
+	if value, found := a.Overrides[key]; found {
+		return value, true
+	}
+	// if value is reset
+	if _, found := a.Overrides["!"+key]; found {
+		return "", false
+	}
+	if value, found := a.Content[key].(string); found {
+		return value, true
+	}
+	// TODO: raise a warning if there was no entry found
+	return "", false
+}
+
+// GetAsStringWithDefault gets the string value for the given key,
+// or returns the given default value
+func (a DocumentAttributesWithOverrides) GetAsStringWithDefault(key, defaultValue string) string {
+	if value, found := a.Overrides[key]; found {
+		return value
+	}
+	if value, found := a.Content[key].(string); found {
+		return value
+	}
+	// TODO: raise a warning if there was no entry found
+	return defaultValue
+}
diff --git a/pkg/types/document_attributes_test.go b/pkg/types/document_attributes_test.go
index bba88a11..657ab00a 100644
--- a/pkg/types/document_attributes_test.go
+++ b/pkg/types/document_attributes_test.go
@@ -4,12 +4,13 @@ import (
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 
 	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/ginkgo/extensions/table"
 	. "github.com/onsi/gomega"
 )
 
 var _ = Describe("document attributes", func() {
 
-	Context("custom attributes", func() {
+	Context("regular attributes", func() {
 
 		It("normal value", func() {
 			// given
@@ -19,26 +20,62 @@ var _ = Describe("document attributes", func() {
 			// then
 			Expect("bar").To(Equal(attributes["foo"]))
 		})
+	})
+})
 
-		It("pointer to value", func() {
-			// given
-			attributes := types.DocumentAttributes{}
-			// when
-			bar := "bar"
-			attributes.Add("foo", &bar)
-			// then
-			Expect("bar").To(Equal(attributes["foo"]))
-		})
+var _ = DescribeTable("document attribute overrides",
+	func(key string, expectedValue string, expectedFound bool) {
+		// given
+		attributes := types.DocumentAttributesWithOverrides{
+			Content: map[string]interface{}{
+				"normal":   "ok",
+				"override": "ok, too",
+			},
+			Overrides: map[string]string{
+				"foo":      "cheesecake",
+				"!bar":     "",
+				"baz":      "",
+				"override": "overridden",
+			},
+		}
+		// when
+		value, found := attributes.GetAsString(key)
+		// then
+		Expect(found).To(Equal(expectedFound))
+		Expect(value).To(Equal(expectedValue))
+	},
+	Entry("normal", "normal", "ok", true),
+	Entry("override", "override", "overridden", true), // entry is overridden
+	Entry("foo", "foo", "cheesecake", true),
+	Entry("!bar", "bar", "", false), // entry is reset
+	Entry("baz", "baz", "", true),   // entry exists but its value is empty
+)
 
-		It("nil value", func() {
-			// given
-			attributes := types.DocumentAttributes{}
-			// when
-			attributes.Add("foo", nil)
-			// then
-			_, found := attributes["foo"]
-			Expect(found).To(BeFalse())
-		})
+var _ = DescribeTable("document attribute overrides with default",
+	func(key string, expectedValue string) {
+		// given
+		attributes := types.DocumentAttributesWithOverrides{
+			Content: map[string]interface{}{
+				"normal":   "ok",
+				"override": "ok, too",
+			},
+			Overrides: map[string]string{
+				"foo":      "cheesecake",
+				"!bar":     "",
+				"baz":      "",
+				"override": "overridden",
+			},
+		}
+		// when
+		value := attributes.GetAsStringWithDefault(key, "default")
+		// then
+		Expect(value).To(Equal(expectedValue))
+	},
+	Entry("normal", "normal", "ok"),
+	Entry("override", "override", "overridden"), // entry is overridden
+	Entry("foo", "foo", "cheesecake"),
+	Entry("!bar", "bar", "default"), // entry is reset, default is returned
+	Entry("baz", "baz", ""),         // entry exists but its value is empty
+)
 
-	})
-})
+//
diff --git a/pkg/types/element_attributes.go b/pkg/types/element_attributes.go
index 25ff908a..d85c7523 100644
--- a/pkg/types/element_attributes.go
+++ b/pkg/types/element_attributes.go
@@ -14,15 +14,17 @@ import (
 // ------------------------------------------
 
 const (
-	// AttrID the key to retrieve the ID in the element attributes
+	// AttrID the key to retrieve the ID
 	AttrID string = "id"
+	// AttrAuthor the key to retrieve the author in the attributes
+	AttrAuthor string = "author"
 	// AttrCustomID the key to retrieve the flag that indicates if the element ID is custom or generated
 	AttrCustomID string = "customID"
-	// AttrIDPrefix the key to retrieve the ID Prefix in the element attributes
+	// AttrIDPrefix the key to retrieve the ID Prefix
 	AttrIDPrefix string = "idprefix"
-	// DefaultIDPrefix the default ID Prefix in the element attributes
+	// DefaultIDPrefix the default ID Prefix
 	DefaultIDPrefix string = "_"
-	// AttrTitle the key to retrieve the title in the element attributes
+	// AttrTitle the key to retrieve the title
 	AttrTitle string = "title"
 	// AttrAuthors the key to the authors declared after the section level 0 (at the beginning of the doc)
 	AttrAuthors string = "authors"
@@ -32,11 +34,11 @@ const (
 	AttrTableOfContents string = "toc"
 	// AttrTableOfContentsLevels the document attribute which specifies the number of levels to display in the ToC
 	AttrTableOfContentsLevels string = "toclevels"
-	// AttrRole the key to retrieve the role in the element attributes
+	// AttrRole the key to retrieve the role
 	AttrRole string = "role"
-	// AttrInlineLink the key to retrieve the link in the element attributes
+	// AttrInlineLink the key to retrieve the link
 	AttrInlineLink string = "link"
-	// AttrAdmonitionKind the key to retrieve the kind of admonition in the element attributes, if a "masquerade" is used
+	// AttrAdmonitionKind the key to retrieve the kind of admonition , if a "masquerade" is used
 	AttrAdmonitionKind string = "admonitionKind"
 	// AttrQuoteAuthor attribute for the author of a verse
 	AttrQuoteAuthor string = "quoteAuthor"
diff --git a/pkg/types/types.go b/pkg/types/types.go
index 3cc8d240..d6463c5a 100644
--- a/pkg/types/types.go
+++ b/pkg/types/types.go
@@ -435,7 +435,7 @@ func NewSection(level int, title []interface{}, ids []interface{}, attributes in
 }
 
 // ResolveID resolves/updates the "ID" attribute in the section (in case the title changed after some document attr substitution)
-func (s Section) ResolveID(docAttributes DocumentAttributes) (Section, error) {
+func (s Section) ResolveID(docAttributes DocumentAttributesWithOverrides) (Section, error) {
 	if !s.Attributes.GetAsBool(AttrCustomID) {
 		replacement, err := ReplaceNonAlphanumerics(s.Title, "_")
 		if err != nil {
@@ -1036,7 +1036,7 @@ func NewExternalCrossReference(location Location, attributes ElementAttributes)
 
 // ResolveLocation resolves the image path using the given document attributes
 // also, updates the `alt` attribute based on the resolved path of the image
-func (r ExternalCrossReference) ResolveLocation(attrs DocumentAttributes) ExternalCrossReference {
+func (r ExternalCrossReference) ResolveLocation(attrs DocumentAttributesWithOverrides) ExternalCrossReference {
 	r.Location = r.Location.Resolve(attrs)
 	return r
 }
@@ -1066,7 +1066,7 @@ func NewImageBlock(path Location, inlineAttributes ElementAttributes, attributes
 
 // ResolveLocation resolves the image path using the given document attributes
 // also, updates the `alt` attribute based on the resolved path of the image
-func (b ImageBlock) ResolveLocation(attrs DocumentAttributes) ImageBlock {
+func (b ImageBlock) ResolveLocation(attrs DocumentAttributesWithOverrides) ImageBlock {
 	b.Location = b.Location.Resolve(attrs)
 	if _, found := b.Attributes[AttrImageAlt]; !found {
 		b.Attributes[AttrImageAlt] = resolveAlt(b.Location)
@@ -1091,7 +1091,7 @@ func NewInlineImage(path Location, attributes ElementAttributes) (InlineImage, e
 
 // ResolveLocation resolves the image path using the given document attributes
 // also, updates the `alt` attribute based on the resolved path of the image
-func (i InlineImage) ResolveLocation(attrs DocumentAttributes) InlineImage {
+func (i InlineImage) ResolveLocation(attrs DocumentAttributesWithOverrides) InlineImage {
 	i.Location = i.Location.Resolve(attrs)
 	if _, found := i.Attributes[AttrImageAlt]; !found {
 		i.Attributes[AttrImageAlt] = resolveAlt(i.Location)
@@ -1854,12 +1854,12 @@ const imagesdir = "imagesdir"
 // with their associated values, or their corresponding raw text if
 // no attribute matched
 // returns `true` if some document attribute substitution occurred
-func (l *Location) Resolve(attrs DocumentAttributes) Location {
+func (l *Location) Resolve(attrs DocumentAttributesWithOverrides) Location {
 	content := bytes.NewBuffer(nil)
 	for _, e := range l.Elements {
 		switch e := e.(type) {
 		case DocumentAttributeSubstitution:
-			if value, found := attrs[e.Name].(string); found {
+			if value, found := attrs.GetAsString(e.Name); found {
 				content.WriteString(value)
 			} else {
 				content.WriteRune('{')
diff --git a/pkg/types/types_test.go b/pkg/types/types_test.go
index 49ae8501..77d4284f 100644
--- a/pkg/types/types_test.go
+++ b/pkg/types/types_test.go
@@ -470,10 +470,13 @@ var _ = Describe("tag ranges", func() {
 
 var _ = Describe("location resolution", func() {
 
-	attrs := types.DocumentAttributes{
-		"imagesdir":  "./images",
-		"includedir": "includes",
-		"foo":        "bar",
+	attrs := types.DocumentAttributesWithOverrides{
+		Content: map[string]interface{}{
+			"imagesdir":  "./images",
+			"includedir": "includes",
+			"foo":        "bar",
+		},
+		Overrides: map[string]string{},
 	}
 	DescribeTable("resolve URL",
 		func(actual types.Location, expected types.Location, expectedStr string) {
@@ -679,7 +682,10 @@ var _ = Describe("element id resolution", func() {
 					Elements: []interface{}{},
 				}
 				// when
-				section, err := section.ResolveID(types.DocumentAttributes{})
+				section, err := section.ResolveID(types.DocumentAttributesWithOverrides{
+					Content:   map[string]interface{}{},
+					Overrides: map[string]string{},
+				})
 				// then
 				Expect(err).NotTo(HaveOccurred())
 				Expect(section.Attributes[types.AttrID]).To(Equal("_foo"))
@@ -707,7 +713,10 @@ var _ = Describe("element id resolution", func() {
 					Elements: []interface{}{},
 				}
 				// when
-				section, err := section.ResolveID(types.DocumentAttributes{})
+				section, err := section.ResolveID(types.DocumentAttributesWithOverrides{
+					Content:   map[string]interface{}{},
+					Overrides: map[string]string{},
+				})
 				// then
 				Expect(err).NotTo(HaveOccurred())
 				Expect(section.Attributes[types.AttrID]).To(Equal("_a_link_to_https_foo_com")) // TODO: should be `httpsfoo`
@@ -729,8 +738,11 @@ var _ = Describe("element id resolution", func() {
 					Elements: []interface{}{},
 				}
 				// when
-				section, err := section.ResolveID(types.DocumentAttributes{
-					types.AttrIDPrefix: "custom_",
+				section, err := section.ResolveID(types.DocumentAttributesWithOverrides{
+					Content: map[string]interface{}{
+						types.AttrIDPrefix: "custom_",
+					},
+					Overrides: map[string]string{},
 				})
 				// then
 				Expect(err).NotTo(HaveOccurred())
@@ -759,8 +771,11 @@ var _ = Describe("element id resolution", func() {
 					Elements: []interface{}{},
 				}
 				// when
-				section, err := section.ResolveID(types.DocumentAttributes{
-					types.AttrIDPrefix: "custom_",
+				section, err := section.ResolveID(types.DocumentAttributesWithOverrides{
+					Content: map[string]interface{}{
+						types.AttrIDPrefix: "custom_",
+					},
+					Overrides: map[string]string{},
 				})
 				// then
 				Expect(err).NotTo(HaveOccurred())
@@ -786,8 +801,11 @@ var _ = Describe("element id resolution", func() {
 					Elements: []interface{}{},
 				}
 				// when
-				section, err := section.ResolveID(types.DocumentAttributes{
-					types.AttrIDPrefix: "custom_",
+				section, err := section.ResolveID(types.DocumentAttributesWithOverrides{
+					Content: map[string]interface{}{
+						types.AttrIDPrefix: "custom_",
+					},
+					Overrides: map[string]string{},
 				})
 				// then
 				Expect(err).NotTo(HaveOccurred())
@@ -819,8 +837,11 @@ var _ = Describe("element id resolution", func() {
 					Elements: []interface{}{},
 				}
 				// when
-				section, err := section.ResolveID(types.DocumentAttributes{
-					types.AttrIDPrefix: "custom_",
+				section, err := section.ResolveID(types.DocumentAttributesWithOverrides{
+					Content: map[string]interface{}{
+						types.AttrIDPrefix: "custom_",
+					},
+					Overrides: map[string]string{},
 				})
 				// then
 				Expect(err).NotTo(HaveOccurred())
diff --git a/test/supported_fixtures_test.go b/test/supported_fixtures_test.go
index 626331c6..94c62483 100644
--- a/test/supported_fixtures_test.go
+++ b/test/supported_fixtures_test.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 
 	"github.com/bytesparadise/libasciidoc"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/ginkgo/extensions/table"
@@ -78,7 +79,8 @@ func entries(pattern string) []TableEntry {
 func convert(sourcePath string) (string, error) {
 	// generate the HTML output
 	buff := bytes.NewBuffer(nil)
-	_, err := libasciidoc.ConvertFileToHTML(sourcePath, buff)
+	config := configuration.NewConfiguration(configuration.WithFilename(sourcePath))
+	_, err := libasciidoc.ConvertFileToHTML(buff, config)
 	if err != nil {
 		return "", err
 	}
diff --git a/testsupport/document_attributes.go b/testsupport/document_attributes.go
index 4bcf587d..dc9ba109 100644
--- a/testsupport/document_attributes.go
+++ b/testsupport/document_attributes.go
@@ -1,13 +1,14 @@
 package testsupport
 
 import (
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 )
 
 // DocumentAttributes returns the attributes in the document header
 func DocumentAttributes(actual types.Document) types.DocumentAttributes {
-	ctx := renderer.NewContext(actual)
+	ctx := renderer.NewContext(actual, configuration.NewConfiguration())
 	ctx = renderer.ProcessDocumentHeader(ctx)
 	return ctx.Document.Attributes
 }
diff --git a/testsupport/document_metadata.go b/testsupport/document_metadata.go
index 0570367d..58e76398 100644
--- a/testsupport/document_metadata.go
+++ b/testsupport/document_metadata.go
@@ -6,14 +6,13 @@ import (
 	"time"
 
 	"github.com/bytesparadise/libasciidoc"
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 )
 
 // DocumentMetadata processes the actual input into a document and returns its metadata
 func DocumentMetadata(actual string, lastUpdated time.Time) (types.Metadata, error) {
-	return libasciidoc.ConvertToHTML("", strings.NewReader(actual),
+	return libasciidoc.ConvertToHTML(strings.NewReader(actual),
 		bytes.NewBuffer(nil),
-		renderer.IncludeHeaderFooter(false),
-		renderer.LastUpdated(lastUpdated))
+		configuration.NewConfiguration(configuration.WithLastUpdated(lastUpdated)))
 }
diff --git a/testsupport/document_metadata_test.go b/testsupport/document_metadata_test.go
index 73650db2..0e0a7e3c 100644
--- a/testsupport/document_metadata_test.go
+++ b/testsupport/document_metadata_test.go
@@ -3,7 +3,7 @@ package testsupport_test
 import (
 	"time"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 	"github.com/bytesparadise/libasciidoc/testsupport"
 
@@ -15,7 +15,7 @@ var _ = Describe("document metadata", func() {
 
 	lastUpdated := time.Now()
 	expected := types.Metadata{
-		LastUpdated: lastUpdated.Format(renderer.LastUpdatedFormat),
+		LastUpdated: lastUpdated.Format(configuration.LastUpdatedFormat),
 		TableOfContents: types.TableOfContents{
 			Sections: []types.ToCSection{
 				{
diff --git a/testsupport/html5_template_matcher.go b/testsupport/html5_template_matcher.go
index 762abaf9..73989335 100644
--- a/testsupport/html5_template_matcher.go
+++ b/testsupport/html5_template_matcher.go
@@ -5,7 +5,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	gomegatypes "github.com/onsi/gomega/types"
 	"github.com/pkg/errors"
 )
@@ -35,7 +35,7 @@ func (m *html5TemplateMatcher) Match(actual interface{}) (success bool, err erro
 	} else {
 		return false, errors.Errorf("MatchHTML5Template matcher expects a string (actual: %T)", actual)
 	}
-	m.expected = strings.Replace(m.expected, "{{.LastUpdated}}", m.lastUpdated.Format(renderer.LastUpdatedFormat), 1)
+	m.expected = strings.Replace(m.expected, "{{.LastUpdated}}", m.lastUpdated.Format(configuration.LastUpdatedFormat), 1)
 	return m.expected == m.actual, nil
 }
 
diff --git a/testsupport/include_preamble.go b/testsupport/include_preamble.go
index f25a7b70..352b094d 100644
--- a/testsupport/include_preamble.go
+++ b/testsupport/include_preamble.go
@@ -1,13 +1,14 @@
 package testsupport
 
 import (
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 )
 
 // IncludePreamble returns a document with the Preamble included at the (expected) location
 func IncludePreamble(actual types.Document) types.Document {
-	ctx := renderer.NewContext(actual)
+	ctx := renderer.NewContext(actual, configuration.NewConfiguration())
 	ctx = renderer.IncludePreamble(ctx)
 	return ctx.Document
 }
diff --git a/testsupport/include_table_of_contents_placeholder.go b/testsupport/include_table_of_contents_placeholder.go
index 530dcba8..f95c4680 100644
--- a/testsupport/include_table_of_contents_placeholder.go
+++ b/testsupport/include_table_of_contents_placeholder.go
@@ -1,13 +1,14 @@
 package testsupport
 
 import (
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 )
 
 // IncludeTableOfContentsPlaceHolder includes the table or contents placeholder in the given document
 func IncludeTableOfContentsPlaceHolder(actual types.Document) types.Document {
-	ctx := renderer.NewContext(actual)
+	ctx := renderer.NewContext(actual, configuration.NewConfiguration())
 	ctx = renderer.IncludeTableOfContentsPlaceHolder(ctx)
 	return ctx.Document
 }
diff --git a/testsupport/parse_document.go b/testsupport/parse_document.go
index 48ab4313..33332ba6 100644
--- a/testsupport/parse_document.go
+++ b/testsupport/parse_document.go
@@ -3,6 +3,7 @@ package testsupport
 import (
 	"strings"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/parser"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
 )
@@ -10,5 +11,5 @@ import (
 // ParseDocument parses the actual value into a Document
 func ParseDocument(actual string) (types.Document, error) {
 	r := strings.NewReader(actual)
-	return parser.ParseDocument("", r) //, parser.Debug(true))
+	return parser.ParseDocument(r, configuration.NewConfiguration()) //, parser.Debug(true))
 }
diff --git a/testsupport/parse_draft_document.go b/testsupport/parse_draft_document.go
index 9c159ddd..29759ad4 100644
--- a/testsupport/parse_draft_document.go
+++ b/testsupport/parse_draft_document.go
@@ -3,6 +3,7 @@ package testsupport
 import (
 	"strings"
 
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/parser"
 )
 
@@ -23,7 +24,8 @@ func ParseDraftDocument(actual string, options ...interface{}) (interface{}, err
 	if !c.preprocessing {
 		return parser.ParseReader(c.filename, r, parser.Entrypoint("AsciidocDocument"))
 	}
-	return parser.ParseDraftDocument(c.filename, r)
+	config := configuration.NewConfiguration(configuration.WithFilename(c.filename))
+	return parser.ParseDraftDocument(r, config)
 }
 
 type drafDocumentParserConfig struct {
diff --git a/testsupport/render_html5.go b/testsupport/render_html5.go
index ac576f4a..e18e9371 100644
--- a/testsupport/render_html5.go
+++ b/testsupport/render_html5.go
@@ -6,26 +6,19 @@ import (
 	"strings"
 
 	"github.com/bytesparadise/libasciidoc"
-	"github.com/bytesparadise/libasciidoc/pkg/renderer"
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/pkg/errors"
 )
 
 // RenderHTML5Body renders the HTML body using the given source
-func RenderHTML5Body(actual string, options ...interface{}) (string, error) {
-	c := &html5RendererConfig{
-		filename: "test.adoc",
-		opts:     []renderer.Option{},
-	}
-	for _, o := range options {
-		if configure, ok := o.(FilenameOption); ok {
-			configure(c)
-		} else if opt, ok := o.(renderer.Option); ok {
-			c.opts = append(c.opts, opt)
-		}
+func RenderHTML5Body(actual string, options ...configuration.Setting) (string, error) {
+	config := configuration.NewConfiguration()
+	for _, set := range options {
+		set(&config)
 	}
 	contentReader := strings.NewReader(actual)
 	resultWriter := bytes.NewBuffer(nil)
-	_, err := libasciidoc.ConvertToHTML(c.filename, contentReader, resultWriter, c.opts...)
+	_, err := libasciidoc.ConvertToHTML(contentReader, resultWriter, config)
 	if err != nil {
 		return "", err
 	}
@@ -36,21 +29,14 @@ func RenderHTML5Body(actual string, options ...interface{}) (string, error) {
 }
 
 // RenderHTML5Title renders the HTML body using the given source
-func RenderHTML5Title(actual string, options ...interface{}) (string, error) {
-	c := &html5RendererConfig{
-		filename: "test.adoc",
-		opts:     []renderer.Option{},
-	}
-	for _, o := range options {
-		if configure, ok := o.(FilenameOption); ok {
-			configure(c)
-		} else if opt, ok := o.(renderer.Option); ok {
-			c.opts = append(c.opts, opt)
-		}
+func RenderHTML5Title(actual string, options ...configuration.Setting) (string, error) {
+	config := configuration.NewConfiguration()
+	for _, set := range options {
+		set(&config)
 	}
 	contentReader := strings.NewReader(actual)
 	resultWriter := bytes.NewBuffer(nil)
-	metadata, err := libasciidoc.ConvertToHTML(c.filename, contentReader, resultWriter, c.opts...)
+	metadata, err := libasciidoc.ConvertToHTML(contentReader, resultWriter, config)
 	if err != nil {
 		return "", err
 	}
@@ -61,26 +47,18 @@ func RenderHTML5Title(actual string, options ...interface{}) (string, error) {
 }
 
 // RenderHTML5Document a custom matcher to verify that a block renders as expected
-func RenderHTML5Document(filename string, options ...renderer.Option) (string, error) {
+func RenderHTML5Document(filename string, options ...configuration.Setting) (string, error) {
 	resultWriter := bytes.NewBuffer(nil)
-	options = append(options, renderer.IncludeHeaderFooter(true))
-	_, err := libasciidoc.ConvertFileToHTML(filename, resultWriter, options...)
-	if err != nil {
-		return "", err
-	}
+	config := configuration.NewConfiguration(append(options, configuration.WithFilename(filename))...)
 	stat, err := os.Stat(filename)
 	if err != nil {
 		return "", errors.Wrapf(err, "unable to get stats for file '%s'", filename)
 	}
-	result := strings.Replace(resultWriter.String(), "{{.LastUpdated}}", stat.ModTime().Format(renderer.LastUpdatedFormat), 1)
-	return result, nil
-}
-
-type html5RendererConfig struct {
-	filename string
-	opts     []renderer.Option
-}
-
-func (c *html5RendererConfig) setFilename(f string) {
-	c.filename = f
+	config.LastUpdated = stat.ModTime()
+	_, err = libasciidoc.ConvertFileToHTML(resultWriter, config)
+	if err != nil {
+		return "", err
+	}
+	// result := strings.Replace(resultWriter.String(), "{{.LastUpdated}}", stat.ModTime().Format(renderer.LastUpdatedFormat), 1)
+	return resultWriter.String(), nil
 }
diff --git a/testsupport/table_of_contents.go b/testsupport/table_of_contents.go
index 6dc8315d..a40cb81b 100644
--- a/testsupport/table_of_contents.go
+++ b/testsupport/table_of_contents.go
@@ -1,6 +1,7 @@
 package testsupport
 
 import (
+	"github.com/bytesparadise/libasciidoc/pkg/configuration"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer"
 	"github.com/bytesparadise/libasciidoc/pkg/renderer/html5"
 	"github.com/bytesparadise/libasciidoc/pkg/types"
@@ -8,6 +9,6 @@ import (
 
 // TableOfContents returns the Table of Contents for the given document
 func TableOfContents(actual types.Document) (types.TableOfContents, error) {
-	ctx := renderer.NewContext(actual)
+	ctx := renderer.NewContext(actual, configuration.NewConfiguration())
 	return html5.NewTableOfContents(ctx)
 }