Skip to content

Latest commit

 

History

History
165 lines (131 loc) · 3.91 KB

index.adoc

File metadata and controls

165 lines (131 loc) · 3.91 KB
Raw

Examples for AsciiDoctor Git includes extension

Table of Contents

Including a file from git

Here’s how to include the code from the first commit (revision fdc094c892b) to lib/asciidoctor-git-include.rb:

.lib/asciidoctor-git-include.rb
[source,ruby]
----
include::git@lib/asciidoctor-git-include.rb[revision=fdc094c892b,lines=5;11..24]
----

The above code, when embedded in an asciidoc, will render selected lines from the file in the specified revision:

lib/asciidoctor-git-include.rb
link:git@lib/asciidoctor-git-include.rb[role=include]

The revision is optional (HEAD is the default) as well as the lines.

Including a diff from git

Include the diff from the second commit (revision d64d85e37b4) to its preceding revision of lib/asciidoctor-git-include.rb:

.Changes introduced in d64d85e37b4
[source,patch]
----
include::git@lib/asciidoctor-git-include.rb[revision=d64d85e37b4,diff,lines=7..17]
----

The above code will render:

Changes introduced in d64d85e37b4
link:git@lib/asciidoctor-git-include.rb[role=include]

Including a diff between any two revisions

Include the diff between two revisions (e3b17ded3 and d64d85e37b4) of lib/asciidoctor-git-include.rb:

.Changes between e3b17ded3 and d64d85e37b4
[source,patch]
----
include::git@lib/asciidoctor-git-include.rb[revision=e3b17ded3,diff=d64d85e37b4,lines=6..18]
----

The above code will render:

Changes between e3b17ded3 and d64d85e37b4
link:git@lib/asciidoctor-git-include.rb[role=include]

Including code or diff from a different repository

The repository attribute can be given to point to an external repository location.

.lib/asciidoctor-git-include.rb
[source,ruby]
----
include::git@lib/asciidoctor-git-include.rb[revision=fdc094c892b,lines=5;24,repository=.]
----

The above code will render:

lib/asciidoctor-git-include.rb
link:git@lib/asciidoctor-git-include.rb[role=include]

The example uses the current repository location for practical reasons, but any local filesystem location should work.

Building this page

Clone the repository.

git clone https://github.com/jakzal/asciidoctor-git-include.git
cd asciidoctor-git-include

Next, choose whether you’d like to use Docker or build the gem directly on your OS. Continue with one of the sections that follow.

Docker

  1. Build the Docker image with the asciidoctor-git-include extension. The docker build command should be run at the top level directory of this project.

    Building the Docker image
    docker build -t jakzal/asciidoctor .

  2. Build the page.

    Building the page with Docker
    docker run -t --rm --name docs -v $(pwd):/project -w /project jakzal/asciidoctor \
    asciidoctor -r asciidoctor-git-include examples/index.adoc -o examples/index.html

  3. Open the generated examples/index.html in a browser.

Gem

  1. Install asciidoctor on your system.

    gem install asciidoctor rouge

  2. Build the extension gem and install it on your system.

    Building and installing the gem
    gem build asciidoctor-git-include.gemspec
gem install asciidoctor-git-include-*.gem

    This will the development version. To install the version published to ruby gems run the following command instead:

    gem install asciidoctor-git-include

  3. Build the page

    Building the page with asciidoctor
    asciidoctor -r asciidoctor-git-include examples/index.adoc -o examples/index.html

  4. Open the generated examples/index.html in a browser.