diff --git a/gems/lib/asciidoctor/foodogsquared-extensions.rb b/gems/lib/asciidoctor/foodogsquared-extensions.rb index 7b40f45..ee87700 100644 --- a/gems/lib/asciidoctor/foodogsquared-extensions.rb +++ b/gems/lib/asciidoctor/foodogsquared-extensions.rb @@ -2,6 +2,7 @@ require 'asciidoctor' require 'asciidoctor/extensions' require_relative 'man-inline-macro/extension' require_relative 'swhid-inline-macro/extension' +require_relative 'github-link-inline-macro/extension' require_relative 'github-raw-content-include-processor/extension' require_relative 'gitlab-raw-content-include-processor/extension' require_relative 'gitlab-link-inline-macro/extension' @@ -9,6 +10,7 @@ require_relative 'gitlab-link-inline-macro/extension' Asciidoctor::Extensions.register do inline_macro ManInlineMacro inline_macro SWHInlineMacro + inline_macro GitHubLinkInlineMacro include_processor GitHubRawIncludeProcessor include_processor GitLabRawIncludeProcessor inline_macro GitLabLinkInlineMacro diff --git a/gems/lib/asciidoctor/github-link-inline-macro/README.adoc b/gems/lib/asciidoctor/github-link-inline-macro/README.adoc new file mode 100644 index 0000000..4762028 --- /dev/null +++ b/gems/lib/asciidoctor/github-link-inline-macro/README.adoc @@ -0,0 +1,33 @@ += GitHub link inline macro +:toc: + + +An inline macro that easily links repositories from GitHub. + + +== Synopsis + +[source, asciidoc] +---- +github:$OWNER/$REPO[$CAPTION] +---- + +If caption is missing, the link text will be the namespace (i.e., `$OWNER/$REPO`) of the repo. + + +== Attributes + +There are optional attributes for this macro. + +- `rev` is the commit/branch/tag of the repo to be linked. + +- `path` is the filepath to be linked within the repo. + + +== Example usage + +- `github:foo-dogsquared/website` will link to link:https://github.com/foo-dogsquared/website[my website repository]. + +- `github:NixOS/nixpkgs[nixpkgs nixos-unstable branch, rev=nixos-unstable]` should link to the link:https://github.com/NixOS/nixpkgs/tree/nixos-unstable[NixOS unstable branch of nixpkgs] with a custom link text. + +- `github:errata-ai/vale[Vale v2.3.0 README, path=README.md, rev=v2.3.0]` should link to the link:https://github.com/errata-ai/vale/blob/v2.3.0/README.md[README of Vale v2.3.0]. diff --git a/gems/lib/asciidoctor/github-link-inline-macro/extension.rb b/gems/lib/asciidoctor/github-link-inline-macro/extension.rb new file mode 100644 index 0000000..1c55b0c --- /dev/null +++ b/gems/lib/asciidoctor/github-link-inline-macro/extension.rb @@ -0,0 +1,23 @@ +require 'uri' + +class GitHubLinkInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor + use_dsl + + named :github + name_positional_attributes 'caption' + + def process parent, target, attrs + doc = parent.document + + text = attrs['caption'] || target + uri = URI.parse %(https://github.com/#{target}) + + uri.path += %(/tree/#{attrs['rev']}) if attrs['rev'] + uri.path += %(/#{attrs['path']}) if attrs['path'] + + target = uri.to_s + + doc.register :links, target + create_anchor parent, text, type: :link, target: target + end +end