asciidoctor-foodogsquared-extensions/lib/asciidoctor/git-blob-include-processor/README.adoc

Table of Contents

• Synopsis
• Attributes
• Extra notes
• Example usage

An include processor that includes content from the current Git repo. The use case for this is specifically for creating dedicated branches for certain content.

Synopsis

link:git:$REVSPEC[role=include]

Where $REVSPEC is a revision as specified in gitrevisions.7. Take note this include processor only accepts a blob object’s content to be extracted. This is meant to be used with other attributes. See Attributes for more details.

If the resulting operation ends in an error (i.e., non-existing revision, file, something went wrong), it should log a warning and transclude an error.

Attributes

• path is the filepath to be retrieved from the revision. When used with diff, it changes into a semicolon-delimited (;) list of files to make diffs with multiple files.

• context-lines is the number of surrounding lines for the diff. This is only effective if diff option is given.

• other is the other commit to be compared with. This is only effective if diff option is given.

• lines get the specified lines from the path. It uses the same parser as the line specifier from highlighting select lines so the syntax is the same.

There’s also a couple of options for this component. You can give the following options through opts attribute (i.e., opts="diff,reverse").

• diff will show the difference in diff format.

• reverse reverses the sides to be compared.

Extra notes

The extension is composed of two parts: an include processor and a preprocessor.

The preprocessor add a document attribute, doccontentref, which it gives the Git reference for that content. doccontentref is the difference between the process working directory (Dir.pwd) and the base directory of the content to be converted. In case the process working directory is not entirely consistent for several reasons, you could give the attribute rootdir as the basis for the comparison. As another option, you could also manually set doccontentref in case it isn’t applicable (i.e., for multilingual sites in Hugo projects).

The include processor also accepts an empty target with the prefix (i.e., include::git:[]) as a shorthand for include::git:{doccontentref}.

Example usage

The following examples assume that doccontentref points to content/posts/sample.

• include::git:HEAD[path=shell.nix] should transclude the current iteration of shell.nix.

• include::git:{doccontentref}[opts="diff", path=Gemfile] should include a diff of the Gemfile from content/posts/sample branch (assuming that Gemfile has changed).

• include::git:non-existing-rev[opts="diff"] should result in a warning with the non-existing revision.

• include::git:{doccontentref}[path=README, lines=2..5] should transclude the README file from lines 2-5.