asciidoctor-foodogsquared-extensions 1.0.1 → 1.2.1

data/lib/asciidoctor/git-blob-include-processor/README.adoc

@@ -1,68 +0,0 @@
-= Git blob include processor
-:toc:
-
-
-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
-
-[source, asciidoc]
-----
-include::git:$REVSPEC[]
-----
-
-Where `$REVSPEC` is a revision as specified in link:https://manpages.debian.org/gitrevisions.7[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 link:https://docs.asciidoctor.org/asciidoc/latest/verbatim/highlight-lines/[highlighting select lines] so the syntax is the same.
-
-There's also a couple of link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options] for this component.
-You can give the following options through `opts` attribute (i.e., `opts="diff,reverse"`).
-
-- `diff` will show the difference in link:https://en.wikipedia.org/wiki/Diff[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.

data/lib/asciidoctor/git-blob-include-processor/extension.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require 'rugged'
-
-class GitBlobIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
-  def handles?(target)
-    target.start_with? 'git:'
-  end
-
-  def process(doc, reader, target, attrs)
-    repo = Rugged::Repository.discover(__dir__)
-
-    git_object_ref = target.delete_prefix 'git:'
-    git_object_ref = doc.attributes['doccontentref'] if git_object_ref.empty?
-
-    begin
-      git_object = repo.rev_parse git_object_ref
-
-      if attrs.key? 'diff-option'
-        options = {}
-
-        options[:paths] = attrs['path'].split(';') if attrs.key? 'path'
-        options[:context_lines] = attrs['context-lines'] if attrs.key? 'context-lines'
-        options[:reverse] = true if attrs.key? 'reverse-option'
-
-        if attrs.key? 'other'
-          other = repo.rev_parse attrs['other'] || nil
-          reader.push_include git_object.diff(other, **options).patch
-        else
-          reader.push_include git_object.diff(**options).patch
-        end
-      else
-        inner_entry = case git_object.type
-                      when :blob
-                        git_object
-                      when :commit
-                        git_object.tree.path attrs['path']
-                      when :tree
-                        git_object.path attrs['path']
-                      when :tag
-                        git_object.target.tree.path attrs['path']
-                      end
-
-        content = repo.lookup(inner_entry[:oid]).content
-
-        if attrs.key? 'lines'
-          content_lines = content.lines
-          new_content = +''
-          doc.resolve_lines_to_highlight(content, attrs['lines']).each do |line_no|
-            new_content << content_lines.at(line_no - 1)
-          end
-
-          content = new_content
-        end
-
-        reader.push_include content
-      end
-    rescue StandardError => e
-      reader.push_include "Unresolved directive for '#{target}' with the following error:\n#{e}"
-      warn e
-    end
-
-    reader
-  end
-end
-
-class GitContentBranchAttributePreprocessor < Asciidoctor::Extensions::Preprocessor
-  def process(document, reader)
-    base_dir = Pathname.new(document.base_dir)
-    rootdir = if document.attributes['rootdir'].nil?
-                Dir.pwd
-              else
-                document.attributes['rootdir']
-              end
-
-    document.attributes['doccontentref'] = base_dir.relative_path_from(rootdir).to_s
-    reader
-  end
-end

data/lib/asciidoctor/github-link-inline-macro/README.adoc

@@ -1,49 +0,0 @@
-= 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.
-When given no caption, it will update the default caption with `$OWNER/$REPO@$REV`.
-
-- `path` is the filepath to be linked within the repo.
-
-- `issue` accepts the issue number to be linked in the GitHub repo.
-Take note `issue` is exclusive to other attributes and has more precedence.
-For example, if `issue` and `rev` are both present, the link for issue will be the result.
-+
-When given no caption, it will update the default caption with `$OWNER/$REPO#$ISSUE`.
-
-You can also change certain behaviors with the link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options attribute].
-
-- `repo` sets the default link text with only the repo.
-Pretty useful to quickly refer to the name of the software.
-
-
-== Example usage
-
-- `github:foo-dogsquared/website[]` will link to link:https://github.com/foo-dogsquared/website[my website repository] with the link text `foo-dogsquared/website`.
-
-- `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 caption of `nixpkgs nixos-unstable branch`.
-
-- `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].
-
-- `github:neovim/neovim[Neovim cannot open large files properly, issue=614]` should link to https://github.com/neovim/neovim/issues/614[an issue of Neovim] with `Neovim cannot open large files properly` as the link text.
-
-- `github:neovim/neovim[Neovim cannot open large files properly, issue=614, rev=master]` should still link to https://github.com/neovim/neovim/issues/614[an issue of Neovim] since `issue` has more precedence over `rev`.

data/lib/asciidoctor/github-link-inline-macro/extension.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-require 'uri'
-
-class GitHubLinkInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
-  use_dsl
-
-  named :github
-  name_positional_attributes 'caption'
-
-  def process(parent, target, attrs)
-    doc = parent.document
-
-    default_caption = if attrs.key?('repo-option')
-                        target.split('/').at(1)
-                      else
-                        target
-                      end
-    text = attrs['caption'] || default_caption
-    uri = URI.parse %(https://github.com/#{target})
-
-    if attrs.key? 'issue'
-      uri.path += %(/issues/#{attrs['issue']})
-      text << "##{attrs['issue']}" if text == target
-    else
-      uri.path += %(/tree/#{attrs['rev']}) if attrs.key? 'rev'
-      uri.path += %(/#{attrs['path']}) if attrs.key? 'path'
-      text << "@#{attrs['rev']}" if attrs.key?('rev') && text == target
-    end
-
-    target = uri.to_s
-
-    doc.register :links, target
-    create_anchor parent, text, type: :link, target: target
-  end
-end

data/lib/asciidoctor/github-raw-content-include-processor/README.adoc

@@ -1,40 +0,0 @@
-= GitHub raw content include processor
-:toc:
-
-
-This is a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including files from GitHub.
-Take note this will only include files.
-For directories, submodules, or symlinks: they will not be processed and a warning will be issued.
-
-This extension honors the link:https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/[safe mode setting] and link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-uri/[the prerequisites for permitting includes with URI].
-
-The following is the basic form of using this include processor.
-
-[source, asciidoc]
-----
-\include::github:$OWNER/$REPO[]
-----
-
-
-== Extra notes
-
-The include processor will use GitHub API.
-It can create authorized requests by setting a token in `GITHUB_API_BEARER_TOKEN` environment variable.
-For instructions on how to get a token, you can refer to link:https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api?apiVersion=2022-11-28#authenticating[respective documentation].
-
-
-== Attributes
-
-- `path` for the path of the file to be included.
-This is practically required as the root entry of the repository is a directory.
-
-- `rev` is the name of the commit/tag/branch to be checked out.
-
-
-== Example usage
-
-- `include::github:asciidoctor/asciidoctor[path=README.adoc, rev=v2.0.0]` will include the Asciidoc file from the link:https://github.com/asciidoctor/asciidoctor/[Asciidoctor GitHub repo] from the point of `v2.0.0`.
-
-- `include::github:NixOS/nixpkgs[path=shell.nix]` will get the latest revision of `shell.nix` from link:https://github.com/NixOS/nixpkgs[nixpkgs repository].
-
-- `include::github:foo-dogsquared/nixos-config[]` should not be processed considering it points to the root directory of the repository.

data/lib/asciidoctor/github-raw-content-include-processor/extension.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-require 'base64'
-require 'json'
-require 'open-uri'
-require 'uri'
-
-class GitHubRawIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
-  def handles?(target)
-    target.start_with? 'github:'
-  end
-
-  def warn_or_raise(doc, warning)
-    if (doc.safe > Asciidoctor::SafeMode::SERVER) && !(doc.attr? 'allow-uri-read')
-      raise warning
-    else
-      warn warning
-    end
-  end
-
-  def process(doc, reader, target, attrs)
-    src = target.delete_prefix('github:').split('/', 3)
-    owner = src.at 0
-    repo = src.at 1
-    namespaced_repo = "#{owner}/#{repo}"
-
-    path = attrs['path'] || ''
-
-    # For more information, see https://docs.github.com/en/rest/repos/contents.
-    uri = URI.parse %(https://api.github.com/repos/#{owner}/#{repo}/contents/#{path})
-
-    if attrs['rev']
-      query = { ref: attrs['rev'] }
-      uri.query = URI.encode_www_form query
-    end
-
-    begin
-      headers = {
-        'Header' => 'application/vnd.github+json',
-        'X-GitHub-Api-Version' => '2022-11-28'
-      }
-
-      headers['Authorization'] = "Token #{ENV['GITHUB_API_BEARER_TOKEN']}" if ENV['GITHUB_API_BEARER_TOKEN']
-
-      OpenURI.open_uri(uri, headers) do |f|
-        response = JSON.parse(f.read)
-
-        # If the response is an array, it is likely to be a directory. In this
-        # usecase, we'll just list them.
-        content = if response.is_a? Array
-                    warning = %(given path '#{path}' from GitHub repo '#{repo}' is a directory)
-                    warn_or_raise doc, warning
-                    warning
-                  elsif response.is_a? Object
-                    Base64.decode64 response['content'] if response['content'] && response['encoding'] == 'base64'
-                  end
-
-        reader.push_include content, target, target, 1, attrs
-      end
-    rescue OpenURI::HTTPError => e
-      warning = %(error while getting '#{path}' in GitHub repo '#{namespaced_repo}: #{e}')
-      warn_or_raise doc, warning
-      reader.push_include warning, target, target, 1, attrs
-    end
-
-    reader
-  end
-end

data/lib/asciidoctor/gitlab-link-inline-macro/README.adoc

@@ -1,37 +0,0 @@
-= GitLab link inline macro
-:toc:
-
-
-An inline macro for easily linking objects from GitLab instances.
-
-
-== Synopsis
-
-[source, asciidoc]
-----
-gitlab:$OWNER/$REPO[$CAPTION]
-----
-
-
-== Attributes
-
-- `domain` is the base domain of the GitLab instance.
-By default, it points to the official instance of `gitlab.com`.
-
-- `rev` is the commit of the repo.
-By default. it doesn't point to anything which should be in the default branch of the repository.
-
-- `path` is the filepath to be linked.
-
-There are settings that is enabled with the link:https://docs.asciidoctor.org/asciidoc/latest/attributes/options/[options attribute].
-
-- `repo` sets the default caption to be the repo part.
-
-
-== Example usage
-
-- `gitlab:gitlab-org/gitlab[]` will link to link:https://gitlab.com/gitlab-org/gitlab[the GitLab's source code with the default domain].
-
-- `gitlab:gitlab-org/gitlab[rev=0c9f77389424b6c5fd8e96b227e9125a13a07cb3, path=README.md]` should link to the link:https://gitlab.com/gitlab-org/gitlab/-/blob/0c9f77389424b6c5fd8e96b227e9125a13a07cb3/README.md[GitLab's README from 3 years ago].
-
-- `gitlab:GNOME/mutter[domain=gitlab.gnome.org, rev=df653b95adf6462fc731998eb53b0860baa7253c, path=meson.build]` should link to link:https://gitlab.gnome.org/GNOME/mutter/-/blob/df653b95adf6462fc731998eb53b0860baa7253c/meson.build[Mutter v44.beta `meson.build` from GNOME GitLab instance].

data/lib/asciidoctor/gitlab-link-inline-macro/extension.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require 'uri'
-
-class GitLabLinkInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
-  use_dsl
-
-  named :gitlab
-  name_positional_attributes 'caption'
-  default_attributes 'domain' => 'gitlab.com'
-
-  def process(parent, target, attrs)
-    doc = parent.document
-
-    default_caption = if attrs.key?('repo-option')
-                        target.split('/').at(1)
-                      else
-                        target
-                      end
-    text = attrs['caption'] || default_caption
-    uri = URI.parse %(https://#{attrs['domain']}/#{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

data/lib/asciidoctor/gitlab-raw-content-include-processor/README.adoc

@@ -1,44 +0,0 @@
-= GitLab raw content include processor
-:toc:
-
-
-It's a link:https://docs.asciidoctor.org/asciidoctor/latest/extensions/include-processor/[include processor] for easily including raw content from GitLab repositories.
-
-
-== Synopsis
-
-[source, asciidoc]
-----
-include::gitlab/$OWNER/$REPO[rev=$COMMIT, path=$FILEPATH]
-----
-
-
-== Extra notes
-
-A link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[personal access token] is most likely required.
-Get one and place the value in an environment variable `GITLAB_API_PERSONAL_ACCESS_TOKEN`.
-
-
-== Attributes
-
-There are some attributes required to be passed.
-
-- `rev` is the commit to be checked out.
-- `path` is the file path to be included.
-
-Aside from the required attributes, there are optional attributes to configured further.
-
-- `domain` is the domain of the GitLab instance.
-By default, it points to the `gitlab.com` official instance.
-
-- `version` is the version string of the API to be used.
-By default, it uses version `v4`.
-
-
-== Example usage
-
-- `include::gitlab:gitlab-org/gitlab[rev=master, path=README.md]` should include the README content from the master branch of link:https://gitlab.com/gitlab-org/gitlab/[GitLab source code].
-
-- `include::freedesktop-sdk/freedesktop-sdk[rev=bcb3e0de957519e87a4c7b8c0e40af9876e531e7, path=.gitlab-ci.yml]` should transclude the GitLab CI configuration from link:https://gitlab.com/freedesktop-sdk/freedesktop-sdk[Freedesktop SDK].
-
-- `include::World/warp[domain=gitlab.gnome.org, rev=v0.5.2, path=meson_options.txt]` includes `meson_options.txt` from link:https://gitlab.gnome.org/World/warp/[Warp source code] at v0.5.2.

data/lib/asciidoctor/gitlab-raw-content-include-processor/extension.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-require 'base64'
-require 'json'
-require 'open-uri'
-require 'uri'
-
-class GitLabRawIncludeProcessor < Asciidoctor::Extensions::IncludeProcessor
-  def handles?(target)
-    target.start_with? 'gitlab:'
-  end
-
-  def warn_or_raise(doc, warning)
-    if (doc.safe > Asciidoctor::SafeMode::SERVER) && !(doc.attr? 'allow-uri-read')
-      raise warning
-    else
-      warn warning
-    end
-  end
-
-  def process(doc, reader, target, attrs)
-    src = target.delete_prefix('gitlab:').split('/', 2)
-    owner = src.at 0
-    repo = src.at 1
-    namespaced_repo = "#{owner}/#{repo}"
-
-    raise %(there is no 'path' attribute given for GitLab repo '#{namespaced_repo}') unless attrs.key? 'path'
-    raise %(no given ref for getting file in '#{namespaced_repo}') unless attrs.key? 'rev'
-
-    path = attrs['path']
-    rev = attrs['rev']
-
-    domain = attrs['domain'] || 'gitlab.com'
-    version = attrs['version'] || 'v4'
-
-    uri = URI.parse %(https://#{domain}/api/#{version})
-
-    # Set the project.
-    uri += %(/projects/#{URI.encode_www_form_component namespaced_repo})
-
-    # Then the filename.
-    uri += %(/repository/files/#{URI.encode_www_form_component path})
-
-    # Then the revision.
-    query = { ref: rev }
-    uri.query = URI.encode_www_form query
-
-    content = begin
-      headers = { 'Content-Type' => 'application-json' }
-      header['PRIVATE-TOKEN'] = ENV['GITLAB_API_PERSONAL_ACCESS_TOKEN'] if ENV['GITLAB_API_PERSONAL_ACCESS_TOKEN']
-
-      OpenURI.open_uri(uri, headers) do |f|
-        response = JSON.parse(f.read)
-
-        Base64.decode64 response['content'] if response['content'] && response['encoding'] == 'base64'
-      end
-    rescue OpenURI::HTTPError => e
-      warning = %(error while getting '#{path}' in GitLab repo '#{repo}': #{e})
-      warn_or_raise doc, warning
-      warning
-    end
-
-    reader.push_include content, target, target, 1, attrs
-    reader
-  end
-end

data/lib/asciidoctor/helpers.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-class String
-  def to_kebab
-    self.gsub(/\s+/, '-')           # Replace all spaces with dashes.
-        .gsub(/[^a-zA-Z0-9-]/, '')  # Remove all non-alphanumerical (and dashes) characters.
-        .gsub(/-+/, '-')            # Reduce all dashes into only one.
-        .gsub(/^-|-+$/, '')         # Remove all leading and trailing dashes.
-        .downcase
-  end
-end
-
-module Asciidoctor
-  module FoodogsquaredCustomExtensions
-    NAME = 'asciidoctor-foodogsquared-custom-extensions'
-    VERSION = '1.0.0'
-    CONTACT_EMAIL = 'foodogsquared@foodogsquared.one'
-    USER_AGENT = "#{NAME}/#{VERSION} ( #{CONTACT_EMAIL} )"
-  end
-end

data/lib/asciidoctor/ietf-rfc-link-inline-macro/README.adoc

@@ -1,27 +0,0 @@
-= Flathub link inline macro
-:toc:
-
-
-A shorthand for linking link:https://datatracker.ietf.org/[IETF RFCs].
-
-
-== Synopsis
-
-[source, asciidoc]
-----
-rfc:$RFC[$CAPTION]
-----
-
-Where...
-
-- `$RFC` is the RFC number.
-
-- `$CAPTION` is the link text to be used.
-By default, it will be `RFC$RFC`.
-
-
-== Example usage
-
-- `rfc:2136[]` links to the link:https://datatracker.ietf.org/doc/html/rfc2136[RFC2136 (dynamic update)] with the caption `RFC2136`.
-
-- `rfc:2136[Dynamic DNS updates]` is the same as the previous list item but with the caption text `Dynamic DNS updates`.

data/lib/asciidoctor/ietf-rfc-link-inline-macro/extension.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-class IETFRFCLinkInlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
-  use_dsl
-
-  named :rfc
-  name_positional_attributes 'caption'
-
-  def process(parent, target, attrs)
-    doc = parent.document
-    url = %(https://datatracker.ietf.org/doc/html/#{target})
-    attrs['caption'] ||= "RFC#{target}"
-    doc.register :links, url
-    create_anchor parent, attrs['caption'], type: :link, target: url
-  end
-end

data/lib/asciidoctor/man-inline-macro/README.adoc

@@ -1,51 +0,0 @@
-= Man inline macro
-:toc:
-
-
-It's a link:https://docs.asciidoctor.org/asciidoctorj/latest/extensions/inline-macro-processor/[inline macro] that easily links manual pages from an online manpage service like link:https://manpages.debian.org/[Debian Manpages].
-
-
-== Synopsis
-
-[source, asciidoc]
-----
-man:$MANPAGE[$VOLNUM]
-----
-
-
-== Attributes
-
-There are optional attributes that can be passed.
-
-- `volnum` expects the section number where the manual page belongs to.
-This attribute is another way to indicate the section in case you start to use more attributes.
-The value from `volnum` attribute has higher precedence.
-When both the positional argument and `volnum` attribute is passed, the `volnum` attribute will be used.
-
-- `service` is the domain of the online manpage service.
-Take note this attribute is only used in `html` backend.
-+
---
-This is an attribute that expects certain values:
-
-- `debian` uses https://manpages.debian.org.
-This is also the default service when no value is given.
-
-- `archlinux` uses https://man.archlinux.org.
-
-- `opensuse` uses https://manpages.opensuse.org.
-
-- `voidlinux` use https://man.voidlinux.org.
-
-- `none` uses none at all. :)
-This is useful if the reference is not found anywhere.
-
-Any invalid value raises an error.
---
-
-
-== Example usage
-
-- `man:crontab[5]` will link to the default manpage service with `crontab(5)` manual page.
-
-- `man:man[volnum=1, service=archlinux]` will link to the link:https://man.archlinux.org/man/man.1[man manpage] from link:https://man.archlinux.org/[man.archlinux.org].