foodogsquared/asciidoctor-foodogsquared-extensions
1
0
Fork 0
mirror of https://github.com/foo-dogsquared/asciidoctor-foodogsquared-extensions.git synced 2025-01-31 10:58:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
02bebfef70
asciidoctor-foodogsquared-e.../lib/asciidoctor/git-blob-include-processor/README.adoc

2.3 KiB
Raw Blame History

Table of Contents

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.

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

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.

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.