pax_global_header 0000666 0000000 0000000 00000000064 14522137003 0014507 g ustar 00root root 0000000 0000000 52 comment=3d3fc894019e049500ab89581208ddf7e5edfff8
jekyll-asciidoc-3.0.1/ 0000775 0000000 0000000 00000000000 14522137003 0014556 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/.deep_cover.rb 0000664 0000000 0000000 00000000216 14522137003 0017273 0 ustar 00root root 0000000 0000000 # frozen_string_literal: true
DeepCover.configure do
output 'coverage/report-deep-cover'
paths %w(lib)
reporter :text if ENV['CI']
end
jekyll-asciidoc-3.0.1/.github/ 0000775 0000000 0000000 00000000000 14522137003 0016116 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/.github/workflows/ 0000775 0000000 0000000 00000000000 14522137003 0020153 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/.github/workflows/ci.yml 0000664 0000000 0000000 00000004511 14522137003 0021272 0 ustar 00root root 0000000 0000000 name: CI
on:
push:
branches: ['**']
paths-ignore: ['*.adoc', 'docs/**']
pull_request:
paths-ignore: ['*.adoc', 'docs/**']
#schedule:
#- cron: '30 2 * * MON'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
strategy:
matrix:
os: [ubuntu-latest]
ruby: ['2.4', '2.7', '3.2']
jekyll-version: [~]
pygments-version: [~]
exclude:
# remove entry to mark as primary
- os: ubuntu-latest
ruby: '2.7'
include:
- os: ubuntu-latest
ruby: jruby-9.4
- os: windows-latest
ruby: '2.7'
- os: ubuntu-latest
ruby: '2.7'
pygments-version: '1.2.0'
- os: ubuntu-latest
ruby: '2.7'
jekyll-version: '3.9.0'
- os: ubuntu-latest
ruby: '2.7'
primary: primary
runs-on: ${{ matrix.os }}
env:
BUNDLE_WITHOUT: coverage:docs:lint
SOURCE_DATE_EPOCH: '1521504000'
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Set Jekyll version
if: matrix.jekyll-version
run: echo 'JEKYLL_VERSION=${{ matrix.jekyll-version }}' >> $GITHUB_ENV
- name: Set Pygments version
if: matrix.pygments-version
run: echo 'PYGMENTS_VERSION=${{ matrix.pygments-version }}' >> $GITHUB_ENV
- name: Install prerequisites for Pygments ~> 1.2.0 (Linux)
if: matrix.os == 'ubuntu-latest' && matrix.pygments-version == '1.2.0'
run: sudo apt-get install python2
- name: Enable lint and coverage (primary only)
if: matrix.primary
run: |
echo 'BUNDLE_WITHOUT=docs' >> $GITHUB_ENV
echo 'COVERAGE=deep' >> $GITHUB_ENV
- name: Install Ruby (uses cached dependencies for non-scheduled build)
uses: ruby/setup-ruby@v1
with:
ruby-version: ${{ matrix.ruby }}
bundler-cache: ${{ github.event_name != 'schedule' }}
- name: Install dependencies (scheduled build only)
if: github.event_name == 'schedule'
run: |
bundle config --local path vendor/bundle
bundle --jobs 3 --retry 3
- name: Run linter (primary only)
if: matrix.primary
run: bundle exec rake lint
- name: Run tests
run: bundle exec ruby -w $(bundle exec ruby -e 'print File.join Gem.bindir, %q(rake)') spec
jekyll-asciidoc-3.0.1/.github/workflows/release.yml 0000664 0000000 0000000 00000002230 14522137003 0022313 0 ustar 00root root 0000000 0000000 name: Release
run-name: ${{ github.workflow }} ${{ github.event.inputs.release-version }}
on:
workflow_dispatch:
inputs:
release-version:
description: Enter version to release (e.g., 1.0.1).
required: false
jobs:
perform:
if: github.repository_owner == 'asciidoctor' && github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
environment: releases
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Install Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '2.7'
bundler-cache: false
- name: Configure Bundler
run: |
bundle config --local path vendor/bundle
- name: Install dependencies
run: bundle --jobs 3 --retry 3
- name: Run linter
run: bundle exec rake lint
- name: Run tests
run: bundle exec rake spec
- name: Setup release environment
run: |
echo RELEASE_VERSION=${{ github.event.inputs.release-version }} >> $GITHUB_ENV
echo RELEASE_RUBYGEMS_API_KEY=${{ secrets[format('RUBYGEMS_API_KEY_{0}', github.actor)] }} >> $GITHUB_ENV
- name: Build, tag, and publish gem
run: ./release.sh
jekyll-asciidoc-3.0.1/.gitignore 0000664 0000000 0000000 00000000153 14522137003 0016545 0 ustar 00root root 0000000 0000000 /.ruby-*
/*.gem
/.bundle/
/.yardoc/
/build/
/coverage/
/deep_cover/
/pkg/
/rdoc/
/Gemfile.lock
.idea
*.iml
jekyll-asciidoc-3.0.1/.rubocop.yml 0000664 0000000 0000000 00000004560 14522137003 0017035 0 ustar 00root root 0000000 0000000 AllCops:
TargetRubyVersion: 2.3
Layout/SpaceInsideBlockBraces:
SpaceBeforeBlockParameters: false
Layout/AlignArguments:
EnforcedStyle: with_fixed_indentation
IndentationWidth: 4
Layout/AlignParameters:
EnforcedStyle: with_fixed_indentation
IndentationWidth: 4
Layout/IndentFirstArgument:
Enabled: false
Layout/IndentHeredoc:
Enabled: false
Layout/LeadingCommentSpace:
Enabled: false
Layout/MultilineOperationIndentation:
EnforcedStyle: indented
Layout/RescueEnsureAlignment:
Enabled: false
Lint/AmbiguousBlockAssociation:
Enabled: false
Lint/ParenthesesAsGroupedExpression:
Enabled: false
Metrics/AbcSize:
Enabled: false
Metrics/BlockLength:
Enabled: false
Metrics/BlockNesting:
Max: 4
Metrics/ClassLength:
Enabled: false
Metrics/CyclomaticComplexity:
Enabled: false
Metrics/LineLength:
Max: 120
Metrics/MethodLength:
Enabled: false
Metrics/PerceivedComplexity:
Enabled: false
Naming/ConstantName:
Enabled: false
Naming/FileName:
Enabled: false
Naming/HeredocDelimiterNaming:
Enabled: false
Naming/PredicateName:
NameWhitelist:
- has_yaml_header?
- has_front_matter?
Style/CaseEquality:
Enabled: false
Style/CharacterLiteral:
Enabled: false
Style/ConditionalAssignment:
EnforcedStyle: assign_inside_condition
IncludeTernaryExpressions: false
Style/Documentation:
Enabled: false # FIXME reenable me
Style/DoubleNegation:
Enabled: false
Style/FrozenStringLiteralComment:
Enabled: false
Style/GuardClause:
Enabled: false
Style/HashSyntax:
EnforcedStyle: ruby19_no_mixed_keys
Style/MethodDefParentheses:
EnforcedStyle: require_no_parentheses
Style/MutableConstant:
Enabled: false
Style/MultilineIfModifier:
Enabled: false
Style/MultilineTernaryOperator:
Enabled: false
Style/NestedTernaryOperator:
Enabled: false
Style/NumericPredicate:
EnforcedStyle: comparison
Style/PercentLiteralDelimiters:
PreferredDelimiters:
default: ()
'%w': ()
'%r': //
Style/PerlBackrefs:
Enabled: false
Style/RegexpLiteral:
Enabled: false
Style/RescueStandardError:
EnforcedStyle: implicit
Style/SpecialGlobalVars:
Enabled: false
Style/SymbolArray:
EnforcedStyle: brackets
# I'd like to enable this one, but rubocop gets confused
Style/TernaryParentheses:
Enabled: false
Style/TrailingCommaInArrayLiteral:
EnforcedStyleForMultiline: consistent_comma
Style/TrailingCommaInHashLiteral:
EnforcedStyleForMultiline: consistent_comma
jekyll-asciidoc-3.0.1/.simplecov 0000664 0000000 0000000 00000000144 14522137003 0016557 0 ustar 00root root 0000000 0000000 SimpleCov.start do
add_filter %w(/.bundle/ /spec/)
coverage_dir 'coverage/report-simplecov'
end
jekyll-asciidoc-3.0.1/.yardopts 0000664 0000000 0000000 00000000306 14522137003 0016423 0 ustar 00root root 0000000 0000000 --charset UTF-8
--readme README.adoc
--no-private
--hide-api private
--title "Jekyll AsciiDoc API Docs"
--output-dir apidoc
--exclude /(?:core|jekyll)_ext/
lib/**/*.rb
-
CHANGELOG.adoc
LICENSE.adoc
jekyll-asciidoc-3.0.1/CHANGELOG.adoc 0000664 0000000 0000000 00000021035 14522137003 0016676 0 ustar 00root root 0000000 0000000 = {project-name} Changelog
:project-name: Jekyll AsciiDoc Plugin
:url-repo: https://github.com/asciidoctor/jekyll-asciidoc
This document provides a high-level view of the changes to the {project-name} by release.
For a detailed view of what has changed, refer to the {url-repo}/commits/master[commit history] on GitHub.
== 3.0.1 (2023-11-06) - @mojavelinux
* clear `:base_dir` option if value is `:docdir` and paths with docdir information is not available (such as to `asciidocify` filter) (#270)
* prepend baseurl to value of imagesdir if imagesdir value is root-relative (#177)
=== Details
{url-repo}/releases/tag/v3.0.1[git tag] | {url-repo}/compare/v3.0.0\...v3.0.1[full diff]
== 3.0.0 (2019-08-31) - @mojavelinux
_No changes since previous release._
== 3.0.0.beta.2 (2019-06-03) - @mojavelinux
* allow site-wide AsciiDoc attributes to also be defined on `asciidoc` key in site configuration (#126)
* set date page variable from revdate for any document in a collection (posts or otherwise) (#202)
* allow non-ASCII word character to be used in name of attribute reference in config file
* use File.write instead of IO.write (as IO.write has extra magic we don't need)
* auto-generate excerpts for posts and documents written in AsciiDoc (#200)
== 3.0.0.beta.1 (2018-12-29) - @mojavelinux
* only support Ruby >= 2.2.0 and Jekyll >= 3.0.0
* update tests to only run against supported versions
* load processor eagerly (at end of plugin initialization)
* don't crash if document body is empty (#179)
* process AsciiDoc header if page has only an AsciiDoc header but no body
* honor layout defined in frontmatter defaults (#187)
* allow page layout to be soft set in site config (#193)
* set asciidoc property to true on all AsciiDoc pages (#189)
* set asciidoc property to true on any (AsciiDoc) page enriched by this plugin (i.e., page.asciidoc) (#189)
* don't call nil_or_empty? outside of an Asciidoctor context (#142)
* don't delete category and tag; sync w/ first entry in array of matching property (#160)
* don't coerce a falsy value of page-layout defined in _config.yml to nil
* integrate collections that are not written (output flag is set to false) (#161)
* document how to enable STEM support (#163)
* document that a liquid tag that includes HTML must be enclosed in a passthrough block (#180)
* document that page attributes must be defined in the document header (#172)
* document both the plugins and gems config keys and when to use one vs the other (#159)
* document how to disable publishing for a page
* document how to make a draft post
* recommend installing gems into project and using a .ruby-version file
* pass standalone option through data instead of prepending to content
* set up code coverage reports (#196)
* set up code linter (Rubocop) (#201)
== 2.1.1 (2018-11-08) - @mojavelinux
* honor layout defined in frontmatter defaults (#187)
* don't call nil_or_empty? outside of an Asciidoctor context (#142)
* handle case when document body is empty (#179)
== 2.1.0 (2017-05-21) - @mojavelinux
* Add `tocify_asciidoc` Liquid filter for generating a table of contents from the parsed AsciiDoc document (Jekyll 3+ only) (#37)
* Remove trailing `@` when resolving attribute reference in value of attribute defined in config
* Set minimum version of Ruby to 1.9.3 in the gemspec
* Prefixing attribute defined in config with minus removes previously defined (e.g., built-in) attribute (#123)
* Convert attribute values in config as follows: true becomes empty string; false becomes nil, number becomes string (#127)
* Merge category page variable into categories variable and tag page variable into tags variable (#149)
* Assign document ID to page variable named docid (#146)
* Enable CI for Windows platform by configuring job on AppVeyor
* Catch SyntaxError when using Psych YAML parser with Ruby 1.9.3
* Document that the name of page variable created from a page attribute is automatically lowercased
* Parse the value of the revdate attribute using `Jekyll::Utils.parse_date`
* Document how to assign a specific time to a post
* Document how to make site-wide AsciiDoc attributes accessible to Liquid templates (#137)
* Fix crash when converting an auto-extracted excerpt when base_dir option is set to :docdir
* Add additional documentation and make other minor improvements to the README
== 2.0.1 (2016-07-06) - @mojavelinux
* Align localtime and localdate attributes with site.time and site.timezone (#117)
* Don't register hook callbacks again when regenerating site; use static methods for hook callbacks (#121)
* Bundle CHANGELOG.adoc and test suite in gem
* Minor improvements to README
== 2.0.0 (2016-07-02) - @mojavelinux
* Split source into multiple files; move all classes under the `Jekyll::AsciiDoc` module
* Avoid redundant initialization caused by the jekyll-watch plugin
* Set docdir, docfile, docname, outfile, outdir, and outpath attributes for each file (Jekyll 3+ only) (#59)
- docdir is only set if value of `base_dir` option is `:docdir`
- setting outdir allows proper integration with Asciidoctor Diagram
* Automatically set `imagesoutdir` attribute if `imagesdir` attribute is relative to root
* Pass site information (root, source, destination, baseurl and url) through as AsciiDoc attributes
* Automatically generate stylesheet for Pygments (#30)
* Change default layout to match collection label (#104)
- page for pages, post for posts, collection label for all others
- use layout named default as fallback
* Resolve attribute references in attribute values defined in config (#103)
* Apply AsciiDoc header integration to documents in all collections (#93)
* Document how to create and enable templates to customize the HTML that Asciidoctor generates (#73)
* Allow `base_dir` option to track document directory by setting the value to `:docdir` (Jekyll 3 only) (#80)
* Add a comprehensive test suite (#77)
* Allow site-wide Asciidoctor attributes to be specified as a Hash; convert to Hash if Array is used (#87)
* Interpret page attribute values as YAML data
* Use Jekyll.logger to write log messages (#85)
* Add topic to all log messages
* Restructure configuration keys so all general settings are under the `asciidoc` key (#82)
* Don't enable `hardbreaks` attribute by default (#69)
* Bump minimum version of Jekyll to 2.3.0 and document requirement in README (#76)
* Allow layout to be disabled to create standalone document; add and document additional option values for layout (#63)
* Make front matter header optional (#57)
* Apply site-wide Asciidoctor configuration (options/attributes) when loading document header (#67)
* Disable liquid processor on AsciiDoc files by default; enable using liquid page variable (#65)
* Resolve empty page attribute value as empty string (#70)
* Soft assign linkattrs attribute
* Allow plugin to work in safe mode (#112)
* Major restructure and rewrite of README
* Document how to use plugin with GitLab Pages (#47)
* Document `asciidocify` Liquid filter
{url-repo}/issues?q=milestone%3Av2.0.0[issues resolved] |
{url-repo}/releases/tag/v2.0.0[git tag]
== 1.1.2 (2016-05-10) - @mkobit
* Apply fix for documents that did not contain at least one attribute beginning with `page-` (#60)
{url-repo}/issues?q=milestone%3Av1.1.2[issues resolved] |
{url-repo}/releases/tag/v1.1.2[git tag]
== 1.1.1 (2016-05-07) - @mkobit
* The AsciiDoc document title overrides the title set in the front matter or the auto-generated title (in the case of a post) (#48)
* The AsciiDoc page-related attributes override the matching entries in the page data (i.e., front matter)
* The value of page-related attributes are treated as YAML values (automatic type coercion)
* `page-` is the default prefix for page-related AsciiDoc attributes (e.g., `page-layout`) (#51)
* The key to configure the page attribute prefix is `asciidoc_page_attribute_prefix`; the value should not contain the trailing hyphen (#51)
* The date of a post can be set using the `revdate` AsciiDoc attribute (#53)
* Only configure the Asciidoctor options once (previously it was being called twice in serve mode)
* Set `env` attribute to `site` instead of `jekyll` (#55)
{url-repo}/issues?q=milestone%3Av1.1.1[issues resolved] |
{url-repo}/releases/tag/v1.1.1[git tag]
== 1.0.1 (2016-03-19) - @mkobit
Enables use with Jekyll 3.
It is still compatible with Jekyll 2.
* Jekyll 3 support (#36, #33)
* Documentation and onboarding improvements (#25, #24)
* Improvements to release process (#28)
{url-repo}/issues?q=milestone%3Av1.0.1[issues resolved] |
{url-repo}/releases/tag/v1.0.1[git tag]
== 1.0.0 (2015-01-04) - @paulrayner
Initial release.
{url-repo}/issues?q=milestone%3Av1.0.0[issues resolved] |
{url-repo}/releases/tag/v1.0.0[git tag]
jekyll-asciidoc-3.0.1/Gemfile 0000664 0000000 0000000 00000001405 14522137003 0016051 0 ustar 00root root 0000000 0000000 source 'https://rubygems.org'
gemspec
gem 'asciidoctor', %(~> #{ENV['ASCIIDOCTOR_VERSION']}), require: false if ENV.key? 'ASCIIDOCTOR_VERSION'
gem 'em-websocket', '0.5.2', platform: [:jruby], require: false
gem 'jekyll', %(~> #{ENV['JEKYLL_VERSION']}), require: false if ENV.key? 'JEKYLL_VERSION'
gem 'pygments.rb', %(~> #{ENV['PYGMENTS_VERSION']}), require: false if ENV.key? 'PYGMENTS_VERSION'
# NOTE Windows does not include zoneinfo files, so load tzinfo-data gem
gem 'tzinfo-data', platform: [:x64_mingw, :mingw], require: false
group :coverage do
gem 'deep-cover-core', '~> 1.1.0', require: false
gem 'simplecov', '~> 0.18.0', require: false
end
group :docs do
gem 'yard', require: false
end
group :lint do
gem 'rubocop', '~> 0.74.0', require: false
end
jekyll-asciidoc-3.0.1/LICENSE 0000664 0000000 0000000 00000002117 14522137003 0015564 0 ustar 00root root 0000000 0000000 Copyright (C) 2013-present Dan Allen, Paul Rayner, and the Asciidoctor Project
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
jekyll-asciidoc-3.0.1/README.adoc 0000664 0000000 0000000 00000176473 14522137003 0016365 0 ustar 00root root 0000000 0000000 = Jekyll AsciiDoc Plugin (powered by Asciidoctor)
Dan Allen ; Paul Rayner
v3.0.1, 2023-11-06
// Settings:
:idprefix:
:idseparator: -
ifndef::env-github[:icons: font]
ifdef::env-github,env-browser[]
:toc: macro
:toclevels: 1
endif::[]
ifdef::env-github[]
:status:
:branch: v3.0.x
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// Aliases:
:path-config: pass:q[[.path]___config.yml__]
:conum-guard: {sp}
ifndef::icons[:conum-guard: {sp}#{sp}]
// URIs:
:url-repo: https://github.com/asciidoctor/jekyll-asciidoc
:url-issues: {url-repo}/issues
:url-search-issues: {url-repo}/search?type=Issues
:url-chat: https://chat.asciidoctor.org
:url-gem: https://rubygems.org/gems/jekyll-asciidoc
:url-gem-asciidoctor: https://rubygems.org/gems/asciidoctor
:url-asciidoc: https://asciidoc.org
:url-asciidoctor: https://asciidoctor.org
:url-asciidoctor-backends: https://github.com/asciidoctor/asciidoctor-backends
:url-asciidoctor-docs: {url-asciidoctor}/docs
:url-asciidoctor-diagram: {url-asciidoctor-docs}/asciidoctor-diagram
:url-asciidoctor-manual: {url-asciidoctor-docs}/user-manual
:url-asciidoc-practices: {url-asciidoctor-docs}/asciidoc-recommended-practices
:url-jaq: https://github.com/asciidoctor/jekyll-asciidoc-quickstart
:url-jekyll: https://jekyllrb.com
:url-jekyll-docs: {url-jekyll}/docs
:url-jekyll-discuss: https://talk.jekyllrb.com
:url-front-matter: {url-jekyll-docs}/frontmatter
:url-liquid-templates: {url-jekyll-docs}/templates
:url-variables: {url-jekyll-docs}/variables
:url-graphviz: https://www.graphviz.org
:url-tilt: https://github.com/rtomayko/tilt
:url-yaml: https://en.wikipedia.org/wiki/YAML
:url-guide-publish-gem: https://guides.rubygems.org/publishing/#publishing-to-rubygemsorg
ifdef::status[]
image:https://img.shields.io/gem/v/jekyll-asciidoc.svg[Latest Release, link={url-gem}]
image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright-and-license]
image:{url-repo}/actions/workflows/ci.yml/badge.svg?branch={branch}[Build Status (GitHub Actions),link={url-repo}/actions/workflows/ci.yml?query=branch%3A{branch}]
image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg[Project Chat (Zulip),link={url-chat}]
endif::[]
A plugin for {url-jekyll}[Jekyll] (>= 3.0.0) that converts {url-asciidoc}[AsciiDoc] source files in your site to HTML pages using {url-asciidoctor}[Asciidoctor].
toc::[]
== Overview
The plugin consists of three extensions:
Converter -- `Jekyll::AsciiDoc::Converter`::
Converts AsciiDoc files to HTML pages.
This plugin currently uses Asciidoctor to convert AsciiDoc content.
Generator -- `Jekyll::AsciiDoc::Integrator`::
Promotes eligible AsciiDoc attributes (e.g., doctitle, id, author, and attributes that begin with the page attribute prefix) to page variables.
These attributes are merged with the page variables defined in the front matter header.
Liquid Filters::
* `asciidocify` -- Uses the converter from this plugin to convert a string of AsciiDoc content to HTML.
* `tocify_asciidoc` -- Generates a table of contents in HTML from the parsed AsciiDoc document of the current page (since 2.1.0).
These extensions are registered automatically when the [.app]*jekyll-asciidoc* gem is required.
== Prerequisites
To use this plugin, you must be using Jekyll >= 3.0.0 and Ruby >= 2.4.0 (with development headers installed).
You should also be familiar with creating sites with Jekyll.
If you're not, you should first read the {url-jekyll-docs}[Jekyll documentation] to familiarize yourself with how it works.
Experience with AsciiDoc and Asciidoctor is also helpful, but not a requirement.
Like Jekyll, this plugin was designed for developers, so some assembly is required.
That means you'll be expected to edit configuration, modify HTML templates, and customize CSS to use it fully.
== Installation
This plugin is packaged as a gem named [.app]*{url-gem}[jekyll-asciidoc]* and published to RubyGems.org.
The plugin depends on the [.app]*{url-gem-asciidoctor}[asciidoctor]* gem, which gets installed automatically.
Your method of installation will depend on whether you use Bundler to manage the dependencies for your Jekyll project.
IMPORTANT: Jekyll relies on several native gems, so it's necessary to have the Ruby development headers (e.g., ruby.h) on your machine in order to install AsciiDoc Jekyll (due to the requirements of Jekyll).
The instructions for how to install the Ruby development headers are platform-specific and outside of the scope of this document.
TIP: If you're using RVM, you should add a [.path]_.ruby-version_ file to the project so your shell automatically switches to the correct version of Ruby each time you enter the project.
For more information, refer to the the page https://rvm.io/workflow/projects[RVM Project Workflow].
=== Installation Using Bundler
If you're using Bundler to manage the dependencies for your project (as recommended), simply add the [.app]*jekyll-asciidoc* gem to the `:jekyll_plugins` group in your [.path]_Gemfile_:
[source,ruby]
----
group :jekyll_plugins do
gem 'jekyll-asciidoc'
end
----
Then, run the `bundle` command from Bundler to install the gem:
$ bundle
Jekyll will automatically activate any plugins listed in the `:jekyll_plugins` group.
If you want to keep the installed gems inside the project, use this command instead:
$ bundle config set --local path .bundle/gems
bundle
TIP: Subsequent calls to `bundle` will retain the `path` setting.
Keep in mind that the gems Bundler installs are linked to the current version of Ruby.
If you switch Ruby versions, you'll need to run `bundle` again.
=== Manual Installation
If you're not using Bundler to manage the dependencies for your Jekyll project, you'll need to install the gem manually:
$ [sudo] gem install jekyll-asciidoc
NOTE: The `sudo` prefix is only required if you are installing gems into your system.
To avoid this bad practice, we recommend using RVM (or another Ruby version manager), which sets up Ruby safely in your home directory.
Then add the [.app]*jekyll-asciidoc* gem to the list of gems for Jekyll to load in your site's {path-config} file:
[source,yaml]
----
plugins:
- jekyll-asciidoc
----
If you're running Jekyll < 3.5.0, you'll need to use `gems` in place of `plugins`:
[source,yaml]
----
gems:
- jekyll-asciidoc
----
=== Plugin Ordering
Since the [.app]*jekyll-asciidoc* plugin promotes <> to the front matter, it must run first.
To make sure it does, rearrange the sequence of plugins in your Gemfile or {path-config} file so the [.app]*jekyll-asciidoc* plugin is listed before other plugins.
By doing so, other plugins will be able to access any front matter that this plugin assigns.
Let's consider the case of using the [.app]*jekyll-archives* plugin alongside the [.app]*jekyll-asciidoc* plugin.
[source,ruby]
----
group :jekyll_plugins do
gem 'jekyll-asciidoc'
gem 'jekyll-archives' <1>
end
----
<1> The [.app]*jekyll-archives* plugin should be listed after the [.app]*jekyll-asciidoc* plugin since it needs to access front matter that is promoted from the header of the AsciiDoc document.
== Creating Pages
This plugin converts eligible AsciiDoc files located inside the source directory (by default, the project root) to HTML pages in the generated site.
There are a few conditions that must be met in order for an AsciiDoc file to be eligible:
. The file must have an AsciiDoc file extension (see <>).
. The name of the file must not begin with a dot (`.`) or an underscore (`_`).footnote:excluded_files[Hidden files and folders are automatically excluded by Jekyll.]
. The file must not be located in a folder whose name begins with a dot (`.`) or an underscore (`_`) (unless the folder is a designated collection, such as _posts).footnote:excluded_files[]
. While you can use a Jekyll front matter header, it is not required.
Here's a sample AsciiDoc file that meets these criteria:
.sample.adoc
[source,asciidoc]
----
---
layout: info
permalink: /sample/
---
= Sample Page
:url-asciidoctor: https://asciidoctor.org
This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].
[source,ruby]
puts "Hello, World!"
----
Alternatively, you can define the page variables directly in the AsciiDoc header, which we recommend:
.sample.adoc
[source,asciidoc]
----
= Sample Page
:page-layout: info
:page-permalink: /sample/
:url-asciidoctor: https://asciidoctor.org
This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {url-asciidoctor}[Asciidoctor].
[source,ruby]
puts "Hello, World!"
----
=== Page Attributes
Any AsciiDoc attribute defined in the AsciiDoc document header whose name begins with ``page-``footnote:[The prefix used to label page attributes can be customized.] gets promoted to a {url-variables}[page variables].
The part of the name after the `page-` prefix is _lowercased_ and used as the variable name (e.g., page-layout becomes layout).
The value is processed as {url-yaml}[YAML] data (single-line form).
Since the attribute value is processed as YAML data, you can build nested data structure using the inline YAML syntax.
For example, here's how you can assign a value to the `page.header.image` page variable:
[source,asciidoc]
----
:page-header: { image: logo.png }
----
To define a page attribute that contains multiple words, use either a hyphen or underscore character to connect the words.
[source,asciidoc]
----
:page-short-name: slug
----
IMPORTANT: Page attributes must be defined in the document header.
That means either putting them directly below the document title (the line beginning with a single equals sign in the sample above) or above all other AsciiDoc content if the document title is not defined in AsciiDoc.
The AsciiDoc document header stops after the first blank line.
For more details about the document header, see the https://asciidoctor.org/docs/user-manual/#doc-header[Document Header] chapter in the Asciidoctor User Manual.
IMPORTANT: You may use include directives in the the document header.
However, you must ensure that the file included _does not_ contain blank lines.
CAUTION: If an attribute defined in the header of an AsciiDoc document is not visible to another plugin or Liquid template, you may have a plugin ordering problem.
See <> to learn how to fix it.
=== Specifying a Layout
The most commonly defined page variable is layout, which determines which template is used to wrap the generated content.
Jekyll will look for a template file inside the [.path]_{empty}_layouts_ folder whose root name matches the name of the layout.
For example, if the layout variable has the value `info`, Jekyll looks for a layout template at the path [.path]__layout/info.html_.
If the layout is empty, the auto-selected layout layout is used (documented in the list below).
If the layout is unset or `false`, the AsciiDoc processor will generate a standalone document.
In this case, the page will appear like an HTML file generated by the AsciiDoc processor directly (with the option `header_footer: true`).
If the layout is ~, no layout is applied.
To review, here are the different ways to specify a layout using the AsciiDoc attribute page-layout:
* `:page-layout: info` -- use the layout named `info` (e.g., [.path]__layout/info.html_)
* _not specified_, `:page-layout:` or `:page-layout: _auto` -- use the automatic layout (i.e., `page` for pages, `post` for posts, the singular form of the collection label for a document; if the auto-selected layout isn't available, the layout `default` is used)
* `:!page-layout:` or `:page-layout: false` -- don't use a layout; instead, generate a standalone HTML document
* `:page-layout: none` or `:page-layout: ~` -- don't use a layout or create a standalone HTML document (often produces an HTML fragment); use of the value `~` is discouraged; the value `none` is preferred
=== Disabling Publishing of a Page
To prevent a page from being published, set the page attribute named `page-published` to `false` (which, in turn, sets the page variable named `published` to `false`.
[source,asciidoc]
----
= Top Secret Info
:page-published: false
This page should not be published.
----
=== Implicit Page Variables
In addition to page attributes defined explicitly (e.g., layout, permalink, etc), the following implicit AsciiDoc attributes are also promoted to page variables:
* doctitle (aka the document title) (becomes `title`)
* id (becomes `docid`)
* author
* revdate (becomes `date`; value is converted to a DateTime object; not applied to pages)
Although not an implicit page variable, another very common page variable to set is `page-description`, which becomes `description` in the model.
==== Showing the Document Title
By default, when Asciidoctor converts your document, it does not include the document title in the body (aka `content`) part of the document that is passed to the layout.
Instead, it skims off the document title and assigns it to the model as `page.title`.
If you don't see the document title on the generated page at first, that's normal.
There are two ways to have the document title included in the page:
. Configure the layout to output the document title explicitly
. Configure Asciidoctor to include the document title in the body
The first option is the most typical.
Somewhere in your layout, you should include the following statement:
----
{{ page.title }}
----
This approach gives you the most control over how the document title appears and what HTML is used to enclose it.
If, instead, you want the document title to be included in the body, add the following configuration to your site's {path-config} file:
[source,yaml]
----
asciidoctor:
attributes:
- showtitle=@
----
It's also possible to enable or override this setting per page.
[source,asciidoc]
----
= Page Title
:showtitle:
----
Using either of these approaches, the document title will be shown on the generated page.
==== Giving Your Post the Time of Day
By default, all posts are assigned a date that is computed from the file name (e.g., the date for 2016-03-20-welcome.adoc is 2016-03-20).
If you want to give your post a specific time as well, you can set the `revdate` attribute in the AsciiDoc header.
We recommend using the format `YYYY-MM-DD HH:MM:SS Z` as shown in this example:
[source,asciidoc]
----
= Post Title
Author Name
:revdate: 2016-03-20 10:30:00 -0600
Lorem ipsum.
----
If you don't provide a time zone in the date, the date is assumed to be in the same time zone as the site (which is your local time zone by default).
Alternatively, you can specify the date in the implicit revision line.
In this case, you must substitute the colons in the time part with "h", "m", and "s", respectively, since the colon demarcates the revision remark.
[source,asciidoc]
----
= Post Title
Author Name
2016-03-20 10h30m00s -0600
Lorem ipsum.
----
Note that the revision line must be preceded by the implicit author line.
==== Classifying Your Post
In Jekyll, you classify a post by assigning it to categories and/or tags.
While you can define them in the front matter, as normal, it's also possible to omit the front matter and assign them in the AsciiDoc header instead.
The AsciiDoc attributes to use to assign categories and tags to your post are `page-categories` and `page-tags`, respectively.
The attribute value must be expressed using the inline Array syntax for YAML, which is a comma-separated list of items surrounded by square brackets.
If you only have one item, you can omit the brackets.
In this case, you can also drop the plural from the attribute name.
[source,asciidoc]
----
= Introducing the Jekyll AsciiDoc Plugin
Author Name
:page-category: Tech
:page-tags: [ruby, jekyll, asciidoctor, ssg]
The Jekyll AsciiDoc plugin makes Jekyll awesome.
Why?
Because you can write posts like this one in AsciiDoc!
----
Recall that the value of page attributes is parsed as an inline YAML value.
==== Publishing a Draft Post
You can defer adding a date to a post until it's ready to publish by making it a draft.
To make a draft post, just place it in the [.path]_{empty}_drafts_ folder instead of the [.path]_posts_ folder.
But don't include the date in the filename or AsciiDoc header.
To include the drafts when building the site, pass the `--drafts` flag to the `jekyll` command:
$ jekyll build --drafts
The date of each draft post will be based on the file's last modification time.
When you're ready to publish the post, move the file from the [.path]_{empty}_drafts_ folder to the [.path]_posts_ folder and assign a date to it either by adding it to the filename or by defining the `revdate` attribute in the AsciiDoc header.
=== Enabling Liquid Preprocessing
Unlike other content files, the {url-liquid-templates}[Liquid template preprocessor] is not applied to AsciiDoc files by default (since version 2.0.0 of this plugin).
If you want the Liquid template preprocessor to be applied to an AsciiDoc file (prior to the content being passed to the AsciiDoc processor), you must enable it by setting the `liquid` page variable (shown here defined using a page attribute).
[source,asciidoc]
----
:page-liquid:
----
IMPORTANT: AsciiDoc files may include a {url-front-matter}[front matter header] for defining page variables.
If present, the front matter header must be the very first character of the file.
The front matter header won't be seen--and could distort conversion--if the front matter is preceded by whitespace or a Byte Order Mark (BOM).
NOTE: Since version 2.0.0 of this plugin, you may exclude the front matter header, as shown in the second example above.
Prior to version 2.0.0, you had to include at least an empty front matter header (except for posts).
In these cases, you define all the page variables (e.g., layout) using AsciiDoc page attributes instead of in the front matter.
You can also use a combination of both.
When intermixed, the page attributes defined in the AsciiDoc header take precedence.
Liquid processing does not extend to files included using the AsciiDoc include directive (see {url-issues}/166[#166]).
If you're using the Liquid include tag to include HTML into the AsciiDoc document, you need to enclose it in a passthrough block.
----
++++
{% include file.html %}
++++
----
This is necessary since AsciiDoc will escape HTML by default.
To pass it through raw requires enclosing it in a passthrough block.
=== Preventing Liquid Processing on AsciiDoc Includes
The Liquid preprocessor does not process content included using the AsciiDoc include directive.
However, if those files are otherwise publishable, they are processed independently by Jekyll with the Liquid preprocessor and will appear in your site.
If this is not the behavior you want, you can exclude them from being processed independently using one of the following techniques:
* Place them in an automatically excluded location, such as a directory starting with `_` (e.g. [.path]___includes__).
* Name them in such a way that they are automatically excluded, such as starting the name with `_` ([.path]___excluded-include.yml__).
* Adding them to the https://jekyllrb.com/docs/configuration/options/[excludes] key in the Jekyll configuration.
=== Extracting Excerpts
This plugin will extract an excerpt for any post or document in a collection if the `excerpt` page variable isn't set using the same logic as for Markdown files.
By default, it will use the content between the header and the first blank line.
If the `excerpt` page variable is set, that value will be used instead.
The excerpt will automatically be converted from AsciiDoc to embedded HTML whereever the `excerpt` property is referenced in a Liquid template.
----
{% post.excerpt %}
----
IMPORTANT: Since version 3.0.0 of this plugin, you no longer have to run the excerpt through the `asciidocify` filter since the conversion is already done for you.
In fact, if you do, the HTML in the converted excerpt will be escaped, which is not what you want.
If you want to use a different excerpt separator for AsciiDoc files, set the `excerpt_separator` under the `asciidoc` key in the site configuration.
For example, you can configure the plugin to use the line comment `//more` as the excerpt separator as follows:
[source,yaml]
----
asciidoc:
excerpt_separator: "\n//more\n"
----
If you're only working with AsciiDoc files in your site, you can go ahead and set this for all files by using the top-level property:
[source,yaml]
----
excerpt_separator: "\n//more\n"
----
If the excerpt separator isn't found, the content of the whole document is used instead.
By default, the excerpt is converted to HTML using the article doctype.
If you want to use a different doctype, such as inline, you can set it in the site configuration as follows:
[source,yaml]
----
asciidoc:
excerpt_doctype: inline
----
You can also set the excerpt doctype per page using the page attribute named `page-excerpt_doctype`.
== Building and Previewing Your Site
You can build your site into the [.path]__site_ directory using:
$ jekyll build
If you're using Bundler, prefix each command with `bundle exec`:
[subs=+quotes]
$ *bundle exec* jekyll build
You can preview your site at \http://localhost:4000 using:
$ jekyll serve
The `serve` command monitors the file system and rebuilds the site whenever a change is detected by default (i.e., watch mode).
To disable watch mode, use the `--no-watch` flag:
$ jekyll serve --no-watch
You can also use the `--watch` flag with the `build` command:
$ jekyll build --watch
If you only want Jekyll to build files which have changed, and not the whole site, add the `--incremental` flag:
$ jekyll serve --incremental
or
$ jekyll build --watch --incremental
To see a report of all the files that are processed, add the `--verbose` flag:
$ jekyll build --verbose
IMPORTANT: If you add the `--safe` flag, third-party plugins such as this one are disabled by default.
To reenable the plugin, you must add the name of the gem to the whitelist.
See <> for details.
== Configuration
This section describes the configuration options for this plugin, which are _optional_.
You should at least assign an empty Hash as a default (e.g., `{}`) to the `asciidoc` and `asciidoctor` keys in {path-config}, respectively, if you don't plan on making any further customizations.
[source,yaml]
----
asciidoc: {}
asciidoctor: {}
----
Using these placeholder values prevents initialization from being performed more than once when using watch mode (see https://github.com/jekyll/jekyll/issues/4858[issue jekyll#4858]).
=== AsciiDoc
NOTE: Prior to version 2.0.0 of this plugin, the configuration keys in this section were defined as flat, top-level names (e.g., `asciidoc_ext`).
These names are now deprecated, but still supported.
By default, this plugin uses Asciidoctor to convert AsciiDoc files.
Because Asciidoctor is currently the only option, the default setting is equivalent to the following configuration in {path-config}:
[source,yaml]
----
asciidoc:
processor: asciidoctor
----
IMPORTANT: The `asciidoc` block should only appear _once_ inside {path-config}.
If you define any other options that are documented in this section, you should append them to the `asciidoc` block.
To tell Jekyll which file extensions to match as AsciiDoc files, append the `ext` option to the `asciidoc` block of your {path-config}:
[source,yaml]
----
asciidoc:
ext: asciidoc,adoc,ad
----
The extensions shown in the previous listing are the default values, so you don't need to specify this option if those defaults are sufficient.
AsciiDoc attributes defined in the document header whose names begin with `page-` are promoted to page variables.
The part of the name after the `page-` prefix is used as the key (e.g., page-layout becomes layout).
If you want to change this attribute prefix, append the `page_attribute_prefix` option to the `asciidoc` block of your {path-config}:
[source,yaml]
----
asciidoc:
page_attribute_prefix: jekyll
----
A hyphen is automatically added to the value of this configuration setting if the value is non-empty (e.g, jekyll-).
Since version 2.0.0 of this plugin, all non-hidden AsciiDoc files are processed by default, even those without a front matter header.
If you only want files containing a front matter header to be processed (as was the behavior prior to version 2.0.0), add the `require_front_matter_header` option to the `asciidoc` block of your {path-config}:
[source,yaml]
----
asciidoc:
require_front_matter_header: true
----
=== Asciidoctor
In addition to the built-in attributes in AsciiDoc, the following additional AsciiDoc attributes are automatically defined by this plugin and available to all AsciiDoc-based pages:
....
site-root=(absolute path of root directory)
site-source=(absolute path of source directory)
site-destination=(absolute path of output directory)
site-baseurl=(value of the baseurl config option)
site-url=(value of the url config option)
env=site
env-site
site-gen=jekyll
site-gen-jekyll
builder=jekyll
builder-jekyll
jekyll-version=(value of the Jekyll::VERSION constant)
idprefix
idseparator=-
linkattrs=@
....
The following additional attributes are defined per page:
....
outpath=(path of page relative to baseurl)
....
You can pass custom attributes to AsciiDoc, or override default attributes provided by the plugin, using the `attributes` option of the `asciidoctor` block in your {path-config}.
The value of this option can either be an Array containing key-value pairs:
[source,yaml]
----
asciidoctor:
attributes:
- idprefix=_
- source-highlighter=pygments
- pygments-css=style
----
or key-value pairs defined as a Hash:
[source,yaml]
----
asciidoctor:
attributes:
idprefix: _
source-highlighter: pygments
pygments-css: style
----
When using the Hash syntax, you must use an empty string value to set a valueless attribute such as `sectanchors`:
[source,yaml]
----
asciidoctor:
attributes:
sectanchors: ''
----
By default, an attribute value defined in {path-config} overrides the same attribute set in the front matter or header of a document.
For example, if you set `page-layout` in {path-config}, you won't be able to set it per page.
[source,yaml]
----
asciidoctor:
attributes:
- page-layout=false
----
If you want to allow individual pages to be able to override the attribute, append the charcter `@` to the value in {path-config}:
[source,yaml]
----
asciidoctor:
attributes:
- page-layout=false@
----
You may use attribute references in the attribute value to reference any attribute that's already defined, including implicit attributes.
For example, to set the `iconsdir` attribute based on the `imagesdir` attribute, use the following:
[source,yaml]
----
asciidoctor:
attributes:
imagesdir: /images
iconsdir: '{imagesdir}/icons'
----
CAUTION: If the value begins with an attribute reference, and you're defining the attributes using the Hash syntax, you must enclose the value in quotes.
There are additional edge cases when the value must be enclosed in quotes, so it's generally recommended to use them.
Since version 2.1.0 of this plugin, you can remove a previously defined attribute by prefixing the name with a minus sign (without any space between):
[source,yaml]
----
asciidoctor:
attributes:
-idprefix:
----
In addition to `attributes`, you may define any other option key (e.g., `safe`) recognized by the {url-asciidoctor-manual}#ruby-api-options[Asciidoctor API].
One of those options is `base_dir`, which is covered in the next section.
==== Specifying the Base Directory
In Asciidoctor, the base directory (i.e., `base_dir` option) is used as the root when resolving relative include paths in top-level documents.
By default, this plugin does not specify a base directory when invoking the Asciidoctor API.
Asciidoctor will therefore use the current working directory (i.e., the project root) as the base directory.
If your source directory is not the project root, and you want Asciidoctor to use the source directory as the base directory, set the value of the `base_dir` option to `:source`.
[source,yaml]
----
asciidoctor:
base_dir: :source
...
----
If, instead, you want the base directory to track the directory of the document being processed, and you're using Jekyll 3 or better, you can set the value of the `base_dir` option to `:docdir`.
This behavior matches how Asciidoctor works when running it outside of Jekyll.
Since the base directory is also the jail, we also recommend setting the `safe` option to enable unsafe mode so you can still resolve paths outside of this directory.
[source,yaml]
----
asciidoctor:
base_dir: :docdir
safe: unsafe
...
----
You can also set the `base_dir` option to any relative or absolute path.
In that case, the same value will be used for all documents.
==== Using AsciiDoc attributes in a Liquid template
Let's say you want to reuse your AsciiDoc attributes in a Liquid template.
This section describes how to do it.
Liquid can only access simple data structures, not complex ones like the one used to store site-wide AsciiDoc attributes. (Site-wide AsciiDoc attributes are stored deep within the Jekyll configuration data as a Hash with symbol keys).
This puts them out of the reach of Liquid templates by default.
This plugin must store site-wide AsciiDoc attributes in this way due to how Jekyll is implemented and the lifecycle it exposes for plugins.
That part can't be changed.
The plugin is limited by Jekyll's design.
However, YAML provides a mechanism that we can leverage to expose these attributes to our Liquid templates.
First, you define your AsciiDoc attributes at the top level of your configuration file where Liquid is able to access them.
If you also assign a YAML reference to this key, you can then pass that Hash to the attributes key in the asciidoctor block, thus allowing the configuration to be shared.
[source,yaml]
----
asciidoc_attributes: &asciidoc_attributes
imagesdir=/images
asciidoctor:
attributes: *asciidoc_attributes
...
----
You can now reference one of the site-wide AsciiDoc attributes in the Liquid template as follows:
----
{{ site.asciidoc_attributes.imagesdir }}
----
Keep in mind that the value of the attribute will be unmodified from the value defined in the configuration file.
==== Enabling Hard Line Breaks Globally
Many Jekyll users are used to writing in GitHub-flavored Markdown (GFM), which preserves hard line breaks in paragraph content.
Asciidoctor supports this feature for AsciiDoc files.
(In fact, previous versions of this plugin enabled this behavior by default).
If you want to enable this behavior for AsciiDoc files, add the `hardbreaks` attribute to the Asciidoctor attributes configuration in your site's {path-config} file:
[source,yaml]
----
asciidoctor:
attributes:
- hardbreaks
----
If you still want to allow individual files to be able to override the attribute, append the charcter `@` to the value in the site configuration:
[source,yaml]
----
asciidoctor:
attributes:
- hardbreaks=@
----
If you already have AsciiDoc attributes defined in the {path-config}, the new attribute should be added as a sibling entry in the YAML collection.
WARNING: Keep in mind, if you enable hard line breaks, you won't be able to use the {url-asciidoc-practices}#one-sentence-per-line[one sentence-per-line writing technique].
== Running in Safe Mode
If you want to use this plugin when running Jekyll in safe mode, you must add the [.app]*jekyll-asciidoc* gem to the whitelist in your site's {path-config} file:
[source,yaml]
----
whitelist:
- jekyll-asciidoc
----
Safe mode is enabled either through the `--safe` flag:
$ jekyll build --safe
or the `safe` configuration option in your site's {path-config} file:
[source,yaml]
----
safe: true
----
== Working with AsciiDoc Content in Templates
Jekyll uses the Liquid templating language to process templates.
This plugin defines two additional Liquid filters, `asciidocify` and `tocify_asciidoc`, for working with AsciiDoc content in those templates.
=== Converting a String from AsciiDoc
You can use the `asciidocify` filter to convert an arbitrary AsciiDoc string anywhere in your template.
This filter allows you to compose site-wide data in AsciiDoc, such your site's description or synopsis, then convert it to HTML for use in the page template(s).
Let's assume you've defined a page variable named `synopsis` that you want treat as AsciiDoc.
You can convert it in your template as follows:
----
{{ page.synopsis | asciidocify }}
----
By default, the AsciiDoc content is parsed as an embedded AsciiDoc document.
If the content represents a single paragraph, and you only want to perform inline substitutions on that content, add the `inline` doctype as the filter's first argument:
----
{{ page.synopsis | asciidocify: 'inline' }}
----
=== Generating a Table of Contents
Since version 2.1.0 of this plugin, you can use the `tocify_asciidoc` filter to generate a table of contents from the content of any page that is generated from AsciiDoc.
This filter gives you the ability to place this table of contents anywhere inside the page layout, but outside the main content.
You apply the `tocify_asciidoc` filter to `page.document`, the page variable that resolves to the parsed AsciiDoc document, as shown here:
----
{{ page.document | tocify_asciidoc }}
----
The number of section levels (i.e., depth) shown in the table of contents defaults to the value defined by the `toclevels` attribute in the AsciiDoc document.
To tune the number of levels, pass a numeric value as the filter's first argument.
----
{{ page.document | tocify_asciidoc: 3 }}
----
When you use the `tocify_asciidoc` filter, you'll also want to disable the `toc` attribute in your document.
You can do this using a conditional preprocessor directive.
[source,asciidoc]
----
= Guide
ifndef::env-site[:toc: left]
== Section A
content
== Section B
content
----
By default, the `tocify_asciidoc` filter will insert a table of contents on any page that has even one section below the page title.
It's possible to conditionally disable this by using a Liquid `if` statement in your template with a custom attribute, similar to:
----
{% if page.show-toc != false %}
{{ page.document | tocify_asciidoc }}
{% endif %}
----
Then in the front matter of pages where you do not want a table of contents to appear, use the attribute `:page-show-toc: false`.
Note that since this example uses a custom attribute, its name can be anything you'd like, it only needs to start with with `page-`.
If you change the attribute name from this example, be sure to update the it in the `if` statement as appropriate.
== Customizing the Generated HTML
You can use templates to customize the HTML output that Asciidoctor generates for your site.
Template files can be composed in any templating language that is supported by {url-tilt}[Tilt].
Each template file corresponds to a node in the AsciiDoc document tree (aka AST).
Below are the steps you need to take to configure Asciidoctor to use custom templates with your site.
=== Step {counter:step}: Add Required Gems
You'll first need to add the thread_safe gem as well as the gem for the templating language you plan to use.
We'll assume that you are using Slim.
[source,ruby]
----
gem 'slim', '~> 3.0.7'
gem 'thread_safe', '~> 0.3.5'
----
=== Step {counter:step}: Install New Gems
Now run the `bundle` command to install the new gems.
$ bundle
=== Step {counter:step}: Create a Templates Folder
Next, create a new folder in your site named [.path]__templates_ to store your templates.
$ mkdir _templates
=== Step {counter:step}: Configure Asciidoctor to Load Templates
In your site's {path-config} file, configure Asciidoctor to load the templates by telling it the location where the templates are stored.
[source,yaml]
----
asciidoctor:
template_dir: _templates
attributes: ...
----
=== Step {counter:step}: Compose a Template
The final step is to compose a template.
We'll be customizing the unordered list node.
Name the file [.path]_ulist.html.slim_.
.ulist.html.slim
[source,slim]
----
- if title?
figure.list.unordered id=id
figcaption=title
ul class=[style, role]
- items.each do |_item|
li
span.primary=_item.text
- if _item.blocks?
=_item.content
- else
ul id=id class=[style, role]
- items.each do |_item|
li
span.primary=_item.text
- if _item.blocks?
=_item.content
----
The next time you build your site, Asciidoctor will use your custom template to generate the HTML for unordered lists.
TIP: You can find additional examples of custom templates in the {url-asciidoctor-backends}[asciidoctor-backends] repository.
== Enabling Asciidoctor Extensions
You enable Asciidoctor extensions in much the same way as this plugin.
You just need to get Jekyll to load the source.
If the extension you want to use is published as a gem, and you're using Bundler to manage the dependencies for your project (as recommended), then you simply add the gem to the `jekyll_plugins` group in your [.path]_Gemfile_:
[source,ruby]
----
group :jekyll_plugins do
gem 'asciidoctor-extension-xyz'
end
----
Then, run the `bundle` command from Bundler to install the gem:
$ bundle
If you're not using Bundler to manage the dependencies for your Jekyll project, you'll need to install the gem manually.
Once that's done, add the gem to the list gems for Jekyll to load in your site's {path-config} file:
[source,ruby]
----
plugins:
- asciidoctor-extension-xyz
----
If you're running Jekyll < 3.5.0, you'll need to use `gems` in place of `plugins`:
[source,ruby]
----
gems:
- asciidoctor-extension-xyz
----
If the extension you want to use is not published as a gem, or is something you're developing, then you'll load it like an ad-hoc Jekyll plugin.
Add the file [.path]_asciidoctor-extensions.rb_ to the [.path]__plugins_ folder of your project root (creating the folder if it does not already exist) and populate the file with the following content:
._plugins/asciidoctor-extensions.rb
[source,ruby]
----
require 'asciidoctor/extensions'
Asciidoctor::Extensions.register do
treeprocessor do
process do |doc|
doc
end
end
end
----
Asciidoctor will automatically enable the extensions in this file when it is loaded by Jekyll.
For a concrete example of using an Asciidoctor extension, refer to the next section.
== Enabling Asciidoctor Diagram
{url-asciidoctor-diagram}[Asciidoctor Diagram] is a set of extensions for Asciidoctor that allow you to embed diagrams generated by PlantUML, Graphviz, ditaa, Shaape, and other plain-text diagram tools inside your AsciiDoc documents.
In order to use Asciidoctor Diagram in a Jekyll project successfully, *you must use a version of this plugin >= 2.0.0*.
Other combinations are known to have issues.
IMPORTANT: For Graphviz and PlantUML diagram generation, {url-graphviz}[Graphviz] must be installed (i.e., the `dot` utility must be available on your `$PATH`.
TIP: To follow a start-to-finish tutorial that covers how to integrate Asciidoctor Diagram, see https://gist.github.com/mojavelinux/968623c493190dd61c059c2d85f9bdc3[this gist].
=== Installation
Using Bundler::
+
--
Add the `asciidoctor-diagram` gem to your [.path]_Gemfile_:
[source,ruby,subs=attributes+]
----
group :jekyll_plugins do
gem 'asciidoctor-diagram', '~> 1.5.4' #{conum-guard}<1>
gem 'jekyll-asciidoc'
...
end
----
<1> Customize the version of Asciidoctor Diagram as needed.
Then, run Bundler's install command to install the new gem:
$ bundle
--
Without Bundler::
+
--
Install gems manually
$ [sudo] gem install asciidoctor-diagram
Then, add the `asciidoctor-diagram` gem to the list of plugins for Jekyll to load in your site's {path-config} file:
[source,yaml]
----
plugins:
- asciidoctor-diagram
- jekyll-asciidoc
----
If you're running Jekyll < 3.5.0, you'll need to use `gems` in place of `plugins`:
[source,yaml]
----
gems:
- asciidoctor-diagram
- jekyll-asciidoc
----
--
The preceding configurations are equivalent to passing `-r asciidoctor-diagram` to the `asciidoctor` command.
=== Generated Image Location
Asciidoctor Diagram needs some context in order to write the images to the proper location.
At a minimum, you must set the following configuration in {path-config}:
[source,yaml]
----
asciidoctor:
base_dir: :docdir
safe: unsafe
----
With this configuration, Asciidoctor Diagram will generate images relative to the generated HTML page (i.e., in the same directory) within the destination folder.
WARNING: Jekyll will *delete* the images Asciidoctor Diagram generates unless you follow the instructions in <>.
You can use the following example to test your setup:
._posts/2016-01-01-diagram-sample.adoc
[source,asciidoc]
----
= Diagram Sample
[graphviz,dot-example,svg]
....
digraph g {
a -> b
b -> c
c -> d
d -> a
}
....
----
If you prefer to serve all images from the same folder, assign a value to the `imagesdir` attribute that is relative to the site root:
[source,yaml]
----
asciidoctor:
base_dir: :docdir
safe: unsafe
attributes:
imagesdir: /images
----
With this configuration, Asciidoctor Diagram will generate images into the [.path]_images_ directory within the destination folder.
WARNING: Jekyll will *delete* the images Asciidoctor Diagram generates unless you follow the instructions in <>.
==== Preserving Generated Images
Since Asciidoctor Diagram writes to the output folder, you have to instruct Jekyll not to remove these generated files in the middle of the build process.
One way to do this is to apply a "`monkeypatch`" to Jekyll.
Add the file [.path]_jekyll-ext.rb_ to the [.path]__plugins_ folder of your project root (creating the folder if it does not already exist) and populate the file with the following content:
._plugins/jekyll-ext.rb
[source,ruby]
----
class Jekyll::Cleaner
def cleanup!; end
end
----
An alternative to the monkeypath approach is to identify folders that contain generated images in the `keep_files` option in {path-config}:
[source,yaml]
----
keep_files:
- images
asciidoctor:
base_dir: :docdir
safe: unsafe
attributes:
imagesdir: /images
----
== Enabling STEM Support
Thanks to Asciidoctor, Jekyll AsciiDoc provides built-in support for processing STEM (Science, Technology, Engineering & Math) equations in your AsciiDoc documents.
To enable this support, you just need to do a bit of configuration.
=== Activating the STEM processing
The first thing you need to do is activate the STEM processing integration in the processor itself.
To do that, set the `stem` attribute on the document.
One way is to set the `stem` attribute in the document header:
[source,asciidoc]
----
= Page Title
:stem:
----
Alternatively, you can enable it the `stem` attribute globally for all AsciiDoc documents in your site by adding the following to your site's {path-config} file:
[source,yaml]
----
asciidoctor:
attributes:
- stem
----
To learn more about the built-in STEM integration, see the https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM] chapter in the Asciidoctor User Manual.
=== Adding the STEM assets to the page
Technically, Asciidoctor only prepares the STEM equations for interpretation by https://mathjax.org[MathJax].
That means you have to load MathJax on any page that contains STEM equations (or all pages, if that's easier).
To do so requires some customization of the page layout.
First, create the file [.path]__includes/mathjax.html_ and populate it with the following contents:
[source,html]
----
----
Then, include this file before the closing `
` tag in your page layout.
----
{% include mathjax.html %}
----
With that configuration in place, the STEM equations in your AsciiDoc file will be presented beautifully using MathJax.
== Adding Supplemental Assets
Certain Asciidoctor features, such as icons, require additional CSS rules and other assets to work.
These CSS rules and other assets do not get automatically included in the pages generated by Jekyll.
This section documents how to configure these additional resources.
TIP: If you want to take a shortcut that skips all this configuration, clone the {url-jaq}[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
JAQ provides a page layout out of the box configured to fully style body content generated from AsciiDoc.
=== Setup
The Jekyll AsciiDoc plugin converts AsciiDoc to embeddable HTML.
This HTML is then inserted into the page layout.
You need to augment the layout to include resources typically present in a standalone HTML document that Asciidoctor produces.
. Create a stylesheet in the [.path]_css_ directory named [.path]_asciidoc.css_ to hold additional CSS for body content generated from AsciiDoc.
. Add this stylesheet to the HTML `
` in [.path]_{empty}_includes/head.html_ under the main.css declaration:
+
[source,html]
----
----
=== Stylesheet for Code Highlighting
Asciidoctor integrates with Pygments to provide code highlighting of source blocks in AsciiDoc content.
To enable Pygments, you must install the `pygments.rb` gem.
To do so, add the `pygments.rb` gem to your [.path]_Gemfile_:
[source,ruby]
----
gem 'pygments.rb', '~> 2.3.0'
----
As part of this integration, Asciidoctor generates a custom stylesheet tailored specially to work with the HTML that Asciidocotor produces.
Since this stylesheet is backed by the Pygments API, it provides access to all the themes in Pygments
This plugin will automatically generate a stylesheet for Pygments into the source directory if the AsciiDoc attributes in your site's {path-config} are configured as follows:
* `source-highlighter` has the value `pygments`
* `pygments-css` has the value `class` or is not set
* `pygments-stylesheet` is not unset (if set, it can have any value)
By default, the stylesheet is written to `stylesdir` + `pygments-stylesheet`.
If you want the stylesheet to be written to the [.path]_css_ directory, add the following configuration to your site's `_config.yml` file:
[source,yaml]
----
asciidoctor:
attributes:
stylesdir: css
----
If the `pygments-stylesheet` attribute is not specified, the value defaults to `asciidoc-pygments.css`.
You can customize this value to your liking.
The Pygments theme is selected by the value of the `pygments-style` attribute.
If this attribute is not set, it defaults to `vs`.
The stylesheet file will be created if it does not yet exist or the theme has been changed.
Jekyll will handle copying the file to the output directory.
You'll need to add a line to your template to link to this stylesheet (assuming `stylesdir=css`), such as:
[source,html]
----
----
To disable this feature, either set the `pygments-css` to `style` (to enable inline styles) or unset the `pygments-stylesheet` attribute in your site's {path-config}.
NOTE: It may still be necessary to make some tweaks to your site's stylesheet to accommodate this integration.
=== Font-based Admonition and Inline Icons
To enable font-based admonition and inline icons, you first need to add Font Awesome to [.path]_{empty}_includes/head.html_ file under the asciidoc.css declaration:
[source,html]
----
----
NOTE: You can also link to a local copy of Font Awesome.
Next, you need to add the following CSS rules from the default Asciidoctor stylesheet to the [.path]_css/asciidoc.css_ file:
[source,css]
----
span.icon > .fa {
cursor: default;
}
.admonitionblock td.icon {
text-align: center;
width: 80px;
}
.admonitionblock td.icon [class^="fa icon-"] {
font-size: 2.5em;
text-shadow: 1px 1px 2px rgba(0,0,0,.5);
cursor: default;
}
.admonitionblock td.icon .icon-note:before {
content: "\f05a";
color: #19407c;
}
.admonitionblock td.icon .icon-tip:before {
content: "\f0eb";
text-shadow: 1px 1px 2px rgba(155,155,0,.8);
color: #111;
}
.admonitionblock td.icon .icon-warning:before {
content: "\f071";
color: #bf6900;
}
.admonitionblock td.icon .icon-caution:before {
content: "\f06d";
color: #bf3400;
}
.admonitionblock td.icon .icon-important:before {
content: "\f06a";
color: #bf0000;
}
----
Feel free to modify the CSS to your liking.
Finally, you need to enable the font-based icons in the header of the document:
[source,asciidoc]
----
:icons: font
----
or in the site configuration:
[source,yaml]
----
asciidoctor:
attributes:
- icons=font
...
----
==== Circled Callout Numbers
Circled callout numbers are also linked to the `icons=font` setting, even though they don't rely on the Font Awesome font.
To enable them, you need to add the following additional CSS to the [.path]_css/asciidoc.css_ file:
[source,css]
----
.conum[data-value] {
display: inline-block;
color: #fff !important;
background: rgba(0,0,0,.8);
-webkit-border-radius: 1em;
border-radius: 1em;
text-align: center;
font-size: .75em;
width: 1.67em;
height: 1.67em;
line-height: 1.67em;
font-family: "Open Sans", "DejaVu Sans", sans-serif;
font-style: normal;
font-weight: bold;
}
.conum[data-value] * {
color: #fff !important;
}
.conum[data-value] + b {
display: none;
}
.conum[data-value]::after {
content: attr(data-value);
}
pre .conum[data-value] {
position: relative;
top: -.125em;
}
b.conum * {
color: inherit !important;
}
.conum:not([data-value]):empty {
display: none;
}
----
=== Image-based Admonition and Inline Icons
As an alternative to font-based icons, you can configure Asciidoctor to use image-based icons.
In this case, all you need to do is provide the icons at the proper location.
First, enable image-based icons and configure the path to the icons in the header of the document:
[source,asciidoc]
----
:icons:
:iconsdir: /images/icons
----
or your site configuration:
[source,yaml]
----
asciidoctor:
attributes:
- icons
- iconsdir=/images/icons
----
Then, simply put the icon images that the page needs in the [.path]_images/icons_ directory.
== Publishing Your Site
This section covers several options you have available for publishing your site, including GitHub Pages and GitLab Pages.
=== Using this Plugin on GitHub Pages
GitHub doesn't (yet) whitelist the AsciiDoc plugin, so you must run Jekyll either on your own computer or on a continuous integration (CI) server.
[IMPORTANT]
GitHub needs to hear from enough users that need this plugin to persuade them to enable it.
Our recommendation is to https://github.com/contact[contact support] and keep asking for it.
Refer to the help page https://help.github.com/articles/adding-jekyll-plugins-to-a-github-pages-site[Adding Jekyll Plugins to a GitHub Pages site] for a list of plugins currently supported on GitHub Pages.
_But don't despair!_
You can still automate publishing of the generated site to GitHub Pages using a continuous integration job.
Refer to the https://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html[Automate GitHub Pages publishing with Jekyll and Travis CI^] tutorial to find step-by-step instructions.
You can also refer to the https://github.com/johncarl81/transfuse-site[Transfuse website build^] for an example in practice.
In fact, if you're using Travis CI, it's even easier than that.
Travis CI provides a https://docs.travis-ci.com/user/deployment/pages/[deployer for GitHub Pages]!
Using this deployer, Travis CI can push your generated site to GitHub Pages after a successful build on your behalf, as long as you've completed these steps:
. Create a personal access token on GitHub that has write access to your GitHub repository (public_repo or repo scope)
. Define the token as a secure variable name GITHUB_TOKEN on the Travis CI settings page for your repository
. Add a deploy configuration to your CI job configuration
Here's a sample deploy configuration you can use:
[source,yaml]
----
deploy:
provider: pages
github-token: $GITHUB_TOKEN
local-dir: _site
target-branch: gh-pages
skip-cleanup: true
keep-history: true
on:
branch: master
----
TIP: When using this setup, don't forget to add the [.path]_.nojekyll_ file to the root of the source directory to tell GitHub Pages not to waste time running Jekyll again on the server.
==== Jekyll AsciiDoc Quickstart
If you want to take a shortcut that skips all the steps in the previously mentioned tutorial, clone the {url-jaq}[Jekyll AsciiDoc Quickstart (JAQ)] repository and use it as a starting point for your site.
JAQ includes a Rake build that is preconfigured to deploy to GitHub Pages from Travis CI and also provides a theme (page layout and CSS) that properly styles body content generated from AsciiDoc.
==== Feeling Responsive
If you're looking for a Jekyll theme that provides comprehensive and mature styles and layouts out of the box, check out the https://github.com/Phlow/feeling-responsive[Feeling Responsive] theme.
It includes integration with this plugin, which you simply have to enable.
Refer to the https://phlow.github.io/feeling-responsive/getting-started/[Getting Started] page for a step-by-step guide to get your site started and feeling responsive.
=== Using this Plugin on GitLab Pages
Deployment to GitLab Pages is much simpler.
That's because GitLab allows you to control the execution of Jekyll yourself.
There's no need to mess around with CI jobs and authentication tokens.
You can find all about how to use Jekyll with GitLab Pages in the tutorial https://about.gitlab.com/2016/04/07/gitlab-pages-setup/#option-b-gitlab-ci-for-jekyll-websites[Hosting on GitLab.com with GitLab Pages].
More in-depth information regarding setting up your repository for GitLab Pages can be found in the https://docs.gitlab.com/ee/pages/README.html[GitLab Enterprise Edition / Pages] documentation.
Assuming the following are true:
. The source of your site resides on the master branch (though you can use any branch for this purpose).
. You're using Bundler to manage the dependencies for your project.
You can then use the following [.path]_.gitlab-ci.yml_ file to get starting hosting your Jekyll site on GitLab Pages.
.gitlab-ci.yml
[source,yaml]
----
image: ruby:2.5
cache:
paths:
- .bundle
before_script:
- bundle --path .bundle/gems
pages:
script:
- bundle exec jekyll build -d public --config _config.yml,_config-gitlab.yml -q
artifacts:
paths:
- public
only:
- master
----
This script runs Jekyll on the official Ruby Docker container.
You also need to add an additional configuration file, [.path]__config-gitlab.yml_, to set the `url` and `baseurl` options when deploying your site to GitLab Pages.
._config-gitlab.yml
[source,yaml,subs=attributes+]
----
url: https://.gitlab.io #{conum-guard}<1>
baseurl: / #{conum-guard}<2>
----
<1> Replace `` with your GitLab username or group.
<2> Replace `` with the basename of your project repository.
The next time you push to the master branch, the GitLab Pages runner will execute Jekyll and deploy your site to [.uri]_\https://.gitlab.io/_, where `` is your GitLab username or group and `` is the basename of your project repository.
Like GitHub Pages, you can also have your site respond to a custom domain name, which is explained in the referenced tutorial.
In this case, update the [.path]__config-gitlab.yml_ file with the appropriate values.
CAUTION: At this time, GitLab Pages only works with projects hosted at GitLab.com or on self-hosted GitLab Enterprise Edition instances.
GitLab Community Edition does not support continuous integration and cannot host pages.
== Getting Help
The Jekyll AsciiDoc plugin is developed to help you publish your content quickly and easily.
But we can't achieve that goal without your input.
Your questions and feedback help steer the project, so speak up!
Activity drives progress.
When seeking answers, always start with the official documentation for Jekyll, which can be found on the {url-jekyll}[Jekyll website].
If you have general questions about Jekyll, we recommend you visit the {url-jekyll-discuss}[Jekyll Talk] forum to get assistance.
For questions related to this extension specifically, or general questions about AsciiDoc or Asciidoctor, please post to the #users stream in the {url-chat}[project chat].
For general information about AsciiDoc, look no further than the {url-asciidoctor-manual}[Asciidoctor User Manual].
=== Filing Bug Reports and Feature Requests
This project uses the {url-issues}[GitHub issue tracker] to manage bug reports and feature requests.
If you encounter a problem, please {url-search-issues}[browse or search] the issues to find out if your problem has already been reported.
If it has not, you may {url-issues}/new[submit a new issue].
The best way to get a timely response and quick fix for your issue is to write a detailed report and respond to replies in a timely manner.
If you know Ruby (or you're willing to learn), we encourage you to submit a pull request.
Please include an RSpec behavior that describes how your feature should work or demonstrates the problem you're encountering.
Make sure to send your pull request from a branch in your fork.
If the pull request resolves an issue, please name the branch using the issue number (e.g., issue-N, where N is the issue number).
If you aren't able to submit a pull request, please provide a sample so that the developers can reproduce your scenario.
== Development
To help develop the Jekyll AsciiDoc plugin, or to simply use the development version, you need to retrieve the source from GitHub.
Follow the instructions below to learn how to clone the source, run the tests and install the development version.
=== Retrieve the Source Code
You can retrieve the source code from GitHub using git.
Simply copy the URL of the {url-repo}[GitHub repository] and pass it to the `git clone` command:
[subs=attributes+]
....
git clone {url-repo}
....
Next, switch to the project directory.
$ cd jekyll-asciidoc
=== Install the Dependencies
The dependencies needed to develop the Jekyll AsciiDoc plugin are defined in the [.path]_Gemfile_ at the root of the project.
You'll use Bundler to install these dependencies.
To check if you have Bundler installed, use the `bundle` command to query for the version:
$ bundle --version
If Bundler is not installed, use the `gem` command to install it.
$ [sudo] gem install bundler
Finally, invoke the `bundle` command (which is provided by the bundler gem) from the root of the project to install the dependencies into the project:
$ bundle --path=.bundle/gems
IMPORTANT: Since we've installed dependencies inside the project, it's necessary to prefix all commands (e.g., rake) with `bundle exec`.
=== Running the Tests
The tests are based on RSpec.
The test suite is located in the [.path]_spec_ directory.
You can run the tests using Rake.
$ bundle exec rake spec
For more fine-grained control, you can also run the tests using RSpec directly.
$ bundle exec rspec
If you only want to run a selection of tests, you can do so by assigning those specifications a tag and filtering the test run accordingly.
Start by adding the `focus` tag to one or more specifications:
[source,ruby]
----
it 'should register AsciiDoc converter', focus: true do
expect(site.converters.any? {|c| ::Jekyll::AsciiDoc::Converter === c }).to be true
end
----
Then, run RSpec with the `focus` flag enabled:
$ bundle exec rspec -t focus
You should see that RSpec only runs the specifications that have this flag.
=== Generating Code Coverage
To generate a code coverage report when running tests using simplecov, set the `COVERAGE` environment variable as follows when running the tests:
$ COVERAGE=true bundle exec rake spec
You'll see a total coverage score as well as a link to the HTML report in the output.
The HTML report helps you understand which lines and branches were missed, if any.
Despite being fast, the downside of using simplecov is that it misses branches.
You can use deep-cover to generate a more thorough report.
To do so, set the `COVERAGE` environment variable as follows when running the tests:
$ COVERAGE=deep bundle exec rake spec
You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
The HTML report helps you understand which lines and branches were missed, if any.
////
As an alternative to deep cover's native HTML reporter, you can also use istanbul / nyc.
First, you'll need to have the `nyc` command available on your system:
$ npm install -g nyc
or
$ yarn global add nyc
Next, in addition to the `COVERAGE` environment variable, also set the `DEEP_COVER_REPORTER` environment variable as follows when running the tests:
$ COVERAGE=deep DEEP_COVER_REPORTER=istanbul bundle exec rake spec
You'll see a total coverage score, a detailed coverage report, and a link to HTML report in the output.
The HTML report helps you understand which lines and branches were missed, if any.
////
=== Running the Code Linter
Before you commit code, you should run it through the linter to make sure it adheres to the coding style.
You can run the linter using the following command:
$ bundle exec rake lint
The coding style is enforced by Rubocop.
The rules are defined in [.path]_.rubocop.yml_.
These rules extend from the default rule set provided by Rubocop to match the style of the project.
=== Installing the Gem Locally
You can install the development version of the gem as follows:
$ bundle exec rake install
This allows you to use an unreleased version of the gem to build your site.
If you want to build the gem and install it yourself, use these commands instead:
$ bundle exec rake build
$ [sudo] gem install pkg/jekyll-asciidoc-*.dev.gem
=== Releasing the Gem
When you are ready for a release, first set the version in the file [.path]_lib/jekyll-asciidoc/version.rb_.
Then, commit the change using the following commit message template:
Release X.Y.Z
where `X.Y.Z` is the version number of the gem.
Next, package, tag and release the gem to RubyGems.org, run the following rake task:
$ bundle exec rake release
IMPORTANT: Ensure you have the proper credentials setup as described in the guide {url-guide-publish-gem}[Publishing to RubyGems.org].
Once you finish the release, you should update the version to the next micro version in the sequence using the `.dev` suffix (e.g., 3.0.1.dev).
== About the Project
The Jekyll AsciiDoc plugin, a plugin for the static site generator {url-jekyll}[Jekyll], is a member project of the Asciidoctor organization.
This plugin is developed and supported by volunteers in the Asciidoctor community.
=== Authors
This plugin was created by Dan Allen and Paul Rayner and has received contributions from many other individuals in the Asciidoctor community.
=== Copyright and License
Copyright (C) 2013-2018 Dan Allen, Paul Rayner, and the Asciidoctor Project.
Free use of this software is granted under the terms of the MIT License.
See link:LICENSE[LICENSE] for details.
////
[glossary]
== Glossary
[glossary]
page variable::
Data associated with a page, post or document.
Page variables are defined in the front matter header or as page attributes in the AsciiDoc header.
page attribute::
Any AsciiDoc attribute that gets promoted to a page variable by this plugin.
Before being promoted, the designated prefix is removed from the name.
The value of a page attribute is parse as YAML data.
////
jekyll-asciidoc-3.0.1/Rakefile 0000664 0000000 0000000 00000000127 14522137003 0016223 0 ustar 00root root 0000000 0000000 Dir['tasks/*.rake'].each {|rakefile| load rakefile }
task default: %w(spec lint build)
jekyll-asciidoc-3.0.1/coding-style-guide.adoc 0000664 0000000 0000000 00000011363 14522137003 0021106 0 ustar 00root root 0000000 0000000 = Coding Style Guide
This document describes the coding style used in this project.
It also serves as an incubator for the coding style guide used throughout the Asciidoctor project.
Note that these guidelines are still evolving.
The coding style rules are as follows:
* Indent using 2 spaces, generally.
* Indent successive lines of conditions, method arguments or ternary expressions using 4 spaces (but not data structures or chained method calls).
// Q: are we sure chained method calls should be an exception?
* Don't indent `when` lines in a case block.
* Wrap API docs at 120 characters.
// 80 or 100 seems more comfortable to read
* Leave a single space inside brackets of a Hash (let it breathe).
{ "key" => "value" }
* Use JSON-style key-value pair when key is a Symbol.
{ key: "value" }
* Fully qualify the class name (beginning with `::`) of any type not in the current namespace.
::File.extname path
* Use triple equals to check for type, placing the type on the left hand side.
::Hash === attrs
* Drop parentheses around method arguments of a method definition.
def integrate document, collection_name = nil
...
end
* Drop parentheses around method arguments of an isolated method call.
source = ::File.expand_path config['source']
+
if key.start_with? '!'
...
end
* Don't surround expression value of variable assignment in parantheses.
part = section.sectname == 'part'
subs = format_mark == '`' ? BASIC_SUBS : NORMAL_SUBS
* Drop parentheses when using fallback values for assignments.
//Q: what about in method arguments or array entries?
a, b = $1 || $3, $2 || $4
* When brackets are required for a method call, use lisp-style brackets
(::File.dirname docfile)
* For chained method calls, wrap parentheses around nested method call.
(NOTE: This produces a warning in Ruby < 2).
asciidoctor_config.replace (Utils.symbolize_keys asciidoctor_config)
* Add `%r` prefix to inline regexp when used as the first argument of a method.
files.grep %r/^spec\//
* Use parentheses outside of a method call when parentheses are required.
layout = collection_name ? (collection_name.chomp 's') : 'page'
+
if (::Jekyll::Utils.method dlg_method.name).arity == -1
...
end
* Use parentheses where required, such as around the accumulator seed value for a collection predicate.
hash.each_with_object({}) {|(key, val), accum| accum[key.to_sym] = val }
* Don't put curly braces around entries in an options Hash (i.e., symbol keys).
record_path_info document, source_only: true
* Use a trailing condition for single-line statements.
clear_path_info if Document === document
* Put parentheses around a variable assignment inside a condition.
if (imagesdir = attrs['imagesdir'])
* Use variable reference to check for nil.
if base
* Use `%()` instead of double quotes around interpolated strings.
%(--- #{val})
* Use single quotes around string if interpolation is not required.
'asciidoctor'
* Name constants using pascal style.
NewLine = %(\n)
* Define each static regular expression (regexp) as a constant so it's precompiled.
Append `Rx` suffix to name.
ExtensionRx = /^\.adoc$/
* Place the regular expression (regexp) before the string when creating a match.
ExtensionRx =~ ext
+
ExtensionRx.match ext
* Use parentheses in traditional style when writing test assertions.
expect(site.config['asciidoc']['processor']).to eql('asciidoctor')
expect(result.key? 'icons').to be true
expect(contents).to match('
')
* Use `.size` to get the length of a collection and `.length` to get the length of a string.
"abc".length
[1, 2, 3].size
* Use `+#[0]+` and `+#[-1]+` to get the first and last element of an Array, respectively, rather than `#first` and `#last`.
NOTE: You still have to use `#first` and `#last` on an Enumerable object that's not an Array.
a = [1, 2, 3]
a[0]
a[-1]
* Pass symbol reference to `.map` when invoking no-args method on iteration variable (parens are required).
lines.map(&:strip)
* When calling `raise` to raise an exception, pass the exception class as the first argument and the message as the second.
Write the message as a sentence, but exclude the period.
raise ::ArgumentError, 'Not a valid argument'
* Use name instead of symbol to alias a method.
alias copy original
* When only one private method, add keyword to method definition; otherwise use block form
* Use `do...end` for multi-line blocks and `{ ... }` for single-line blocks (even when chained)
* Use `{}.tap {|accum| arr.each {|v| accum[v] = v } }` to create a Hash from an Array or Hash
* Use default_ as prefix instead of suffix
////
* try to make assignments in condition if scoped to that block
* close empty block on same line if empty - `rescue ::NameError; end`
////
jekyll-asciidoc-3.0.1/jekyll-asciidoc.gemspec 0000664 0000000 0000000 00000003554 14522137003 0021200 0 ustar 00root root 0000000 0000000 require File.absolute_path 'lib/jekyll-asciidoc/version', __dir__
require 'open3' unless defined? Open3
Gem::Specification.new do |s|
s.name = 'jekyll-asciidoc'
s.version = Jekyll::AsciiDoc::VERSION
s.summary = 'A Jekyll plugin that converts the AsciiDoc source files in your site to HTML pages using Asciidoctor.'
s.description = s.summary
s.authors = ['Dan Allen', 'Paul Rayner']
s.email = ['dan.j.allen@gmail.com']
s.homepage = 'https://github.com/asciidoctor/jekyll-asciidoc'
s.license = 'MIT'
s.metadata = {
'bug_tracker_uri' => 'https://github.com/asciidoctor/jekyll-asciidoc/issues',
'changelog_uri' => 'https://github.com/asciidoctor/jekyll-asciidoc/blob/master/CHANGELOG.adoc',
'mailing_list_uri' => 'http://discuss.asciidoctor.org',
'source_code_uri' => 'https://github.com/asciidoctor/jekyll-asciidoc',
}
# NOTE the required ruby version is informational only
# it tracks the minimum version required by Jekyll >= 3.0.0 (see https://jekyllrb.com/docs/installation/#requirements)
# we don't enforce it because it can't be overridden and can cause builds to break
#s.required_ruby_version = '>= 2.2.0'
files = begin
(result = Open3.popen3('git ls-files -z') {|_, out| out.read }.split ?\0).empty? ? Dir['**/*'] : result
rescue ::SystemCallError
Dir['**/*']
end
s.files = files.grep %r/^(?:lib\/.+|Gemfile|LICENSE|(?:CHANGELOG|README)\.adoc|\.yardopts|jekyll-asciidoc\.gemspec)$/
#s.test_files = files.grep %r/^spec\/./
s.require_paths = ['lib']
s.add_runtime_dependency 'asciidoctor', ['>= 1.5.0', '< 3.0.0']
s.add_runtime_dependency 'jekyll', '>= 3.0.0'
s.add_development_dependency 'kramdown-parser-gfm', '~> 1.1.0' # required when testing Jekyll 3
s.add_development_dependency 'pygments.rb', '~> 2.3.0'
s.add_development_dependency 'rake', '~> 13.1.0'
s.add_development_dependency 'rspec', '~> 3.12.0'
end
jekyll-asciidoc-3.0.1/lib/ 0000775 0000000 0000000 00000000000 14522137003 0015324 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc.rb 0000664 0000000 0000000 00000001200 14522137003 0020710 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
jekyll_gem_version = ::Gem::Version.new ::Jekyll::VERSION
Jekyll3_0 = (::Gem::Requirement.new '~> 3.0.0').satisfied_by? jekyll_gem_version
Jekyll3_1 = !Jekyll3_0 && ((::Gem::Requirement.new '~> 3.1.0').satisfied_by? jekyll_gem_version)
end
end
require_relative 'jekyll-asciidoc/core_ext'
require_relative 'jekyll-asciidoc/jekyll_ext'
require_relative 'jekyll-asciidoc/utils'
require_relative 'jekyll-asciidoc/mixins'
require_relative 'jekyll-asciidoc/excerpt'
require_relative 'jekyll-asciidoc/converter'
require_relative 'jekyll-asciidoc/integrator'
require_relative 'jekyll-asciidoc/filters'
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/ 0000775 0000000 0000000 00000000000 14522137003 0020372 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/converter.rb 0000664 0000000 0000000 00000033474 14522137003 0022741 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
class Converter < ::Jekyll::Converter
DefaultAttributes = {
'idprefix' => '',
'idseparator' => '-',
'linkattrs' => '@',
}
DefaultFileExtensions = %w(asciidoc adoc ad)
DefaultPageAttributePrefix = 'page'
ImplicitAttributes = {
'env' => 'site',
'env-site' => '',
'site-gen' => 'jekyll',
'site-gen-jekyll' => '',
'builder' => 'jekyll',
'builder-jekyll' => '',
'jekyll-version' => ::Jekyll::VERSION,
}
MessageTopic = Utils::MessageTopic
NewLine = Utils::NewLine
AttributeReferenceRx = /\\?\{(\p{Word}[-\p{Word}]*)\}/
HeaderBoundaryRx = /(?<=\p{Graph}#{NewLine * 2})/
HeaderLineRx = /^=[ \t]+.|^:!?\w[-\w]*!?:(?:[ \t]+.)?/
# Enable plugin when running in safe mode; jekyll-asciidoc gem must also be declared in whitelist
safe true
# highlighter prefix/suffix not used by this plugin; defined only to avoid warning
highlighter_prefix nil
highlighter_suffix nil
def initialize config
@config = config
@logger = ::Jekyll.logger
@page_context = {}
# NOTE jekyll-watch reinitializes plugins using a shallow clone of config, so no need to reconfigure
# NOTE check for Configured only works if value of key is defined in _config.yml as Hash
unless Configured === (asciidoc_config = (config['asciidoc'] ||= {}))
if ::String === asciidoc_config
@logger.warn MessageTopic,
'The AsciiDoc configuration should be defined using Hash on asciidoc key instead of discrete entries.'
asciidoc_config = config['asciidoc'] = { 'processor' => asciidoc_config }
else
asciidoc_config['processor'] ||= 'asciidoctor'
end
old_asciidoc_ext = config.delete 'asciidoc_ext'
asciidoc_ext = (asciidoc_config['ext'] ||= (old_asciidoc_ext || (DefaultFileExtensions * ',')))
asciidoc_ext_re = asciidoc_config['ext_re'] = /^\.(?:#{asciidoc_ext.tr ',', '|'})$/ix
old_page_attr_prefix_def = config.key? 'asciidoc_page_attribute_prefix'
old_page_attr_prefix_val = config.delete 'asciidoc_page_attribute_prefix'
unless (page_attr_prefix = asciidoc_config['page_attribute_prefix'])
page_attr_prefix = old_page_attr_prefix_def ? old_page_attr_prefix_val || '' :
(asciidoc_config.key? 'page_attribute_prefix') ? '' : DefaultPageAttributePrefix
end
asciidoc_config['page_attribute_prefix'] = (page_attr_prefix = page_attr_prefix.chomp '-').empty? ?
'' : %(#{page_attr_prefix}-)
asciidoc_config['require_front_matter_header'] = !!asciidoc_config['require_front_matter_header']
asciidoc_config.extend Configured
if asciidoc_config['require_front_matter_header']
unless (::Jekyll::Utils.method :has_yaml_header?).owner == ::Jekyll::Utils
# NOTE restore original method
::Jekyll::Utils.extend (::Module.new do
define_method :has_yaml_header?, &(Utils.method :has_yaml_header?)
end)
end
else
::Jekyll::Utils.extend (::Module.new do
define_method :has_yaml_header?,
(Utils.method :has_front_matter?).curry[Utils.method :has_yaml_header?][asciidoc_ext_re]
end)
end
end
if (@asciidoc_config = asciidoc_config)['processor'] == 'asciidoctor'
unless Configured === (@asciidoctor_config = (config['asciidoctor'] ||= {}))
asciidoctor_config = @asciidoctor_config
asciidoctor_config.replace symbolize_keys asciidoctor_config
source = ::File.expand_path config['source']
dest = ::File.expand_path config['destination']
case (base = asciidoctor_config[:base_dir])
when ':source'
asciidoctor_config[:base_dir] = source
when ':docdir'
asciidoctor_config[:base_dir] = :docdir
else
asciidoctor_config[:base_dir] = ::File.expand_path base if base
end
asciidoctor_config[:safe] ||= 'safe'
site_attributes = {
'site-root' => ::Dir.pwd,
'site-source' => source,
'site-destination' => dest,
'site-baseurl' => (baseurl = config['baseurl']),
'site-url' => config['url'],
}
attrs = asciidoctor_config[:attributes] = compile_attributes asciidoctor_config[:attributes],
(compile_attributes asciidoc_config['attributes'],
((site_attributes.merge ImplicitAttributes).merge DefaultAttributes))
if (imagesdir = attrs['imagesdir']) && (imagesdir.start_with? '/')
attrs['imagesoutdir'] = ::File.join dest, (imagesdir.chomp '@') unless attrs.key? 'imagesoutdir'
attrs['imagesdir'] = baseurl + imagesdir unless baseurl.to_s.empty?
end
asciidoctor_config.extend Configured
end
end
load_processor
end
def load_processor
case @asciidoc_config['processor']
when 'asciidoctor'
begin
require 'asciidoctor' unless defined? ::Asciidoctor::VERSION
rescue ::LoadError
@logger.error MessageTopic, 'You\'re missing a library required to convert AsciiDoc files. Install using:'
@logger.error '', '$ [sudo] gem install asciidoctor'
@logger.abort_with 'Bailing out; missing required dependency: asciidoctor'
end
else
@logger.error MessageTopic, %(Invalid AsciiDoc processor given: #{@asciidoc_config['processor']})
@logger.error '', 'Valid options are: asciidoctor'
@logger.abort_with 'Bailing out; invalid Asciidoctor processor.'
end
nil
end
def self.get_instance site
site.find_converter_instance self
end
def matches ext
@asciidoc_config['ext_re'].match? ext
end
def output_ext _ext
'.html'
end
def self.before_render document, payload
(get_instance document.site).before_render document, payload if Document === document || Excerpt === document
end
def self.after_render document
(get_instance document.site).after_render document if Document === document || Excerpt === document
end
def before_render document, payload
# NOTE Jekyll 3.1 incorrectly maps the page payload to document.data instead of payload['page']
@page_context[:data] = ::Jekyll::AsciiDoc::Jekyll3_1 ? document.data : payload['page']
record_paths document
end
def after_render _document
@page_context.clear
end
def record_paths document, opts = {}
@page_context[:paths] = paths = {
'docfile' => (docfile = ::File.join document.site.source, document.relative_path),
'docdir' => (::File.dirname docfile),
'docname' => (::File.basename docfile, (::File.extname docfile)),
}
paths.update(
'outfile' => (outfile = document.destination document.site.dest),
'outdir' => (::File.dirname outfile),
'outpath' => document.url
) unless opts[:source_only]
end
def clear_paths
@page_context.delete :paths
end
def load_header document
record_paths document, source_only: true
case @asciidoc_config['processor']
when 'asciidoctor'
opts = @asciidoctor_config.merge parse_header_only: true
header = extract_header document
if (paths = @page_context[:paths])
if opts[:base_dir] == :docdir
opts[:base_dir] = paths['docdir'] # NOTE this assignment happens inside the processor anyway
else
paths.delete 'docdir'
end
opts[:attributes] = opts[:attributes].merge paths
end
if (layout_attr = resolve_default_layout document, opts[:attributes])
opts[:attributes] = opts[:attributes].merge layout_attr
end
# NOTE return instance even if header is empty since attributes may be inherited from config
doc = ::Asciidoctor.load header, opts
else
@logger.warn MessageTopic,
%(Unknown AsciiDoc processor: #{@asciidoc_config['processor']}. Cannot load document header.)
doc = nil
end
clear_paths
doc
end
def convert content
# NOTE don't use nil_or_empty? since that's only provided only by Asciidoctor
return '' unless content && !content.empty?
case @asciidoc_config['processor']
when 'asciidoctor'
opts = @asciidoctor_config.merge header_footer: (data = @page_context[:data] || {})['standalone']
if (paths = @page_context[:paths])
if opts[:base_dir] == :docdir
opts[:base_dir] = paths['docdir'] # NOTE this assignment happens inside the processor anyway
else
paths.delete 'docdir'
end
opts[:attributes] = opts[:attributes].merge paths
elsif opts[:base_dir] == :docdir
opts.delete :base_dir
end
if (doctype = data['doctype'])
opts[:doctype] = doctype
end
(data['document'] = ::Asciidoctor.load content, opts).extend(Liquidable).convert
else
@logger.warn MessageTopic,
%(Unknown AsciiDoc processor: #{@asciidoc_config['processor']}. Passing through unparsed content.)
content
end
end
private
# Take up to the AsciiDoc document header (if present), then continue to the excerpt separator, if non-blank.
def extract_header document
if (content = document.content)
header = (header_boundary = HeaderBoundaryRx =~ content) ? $` : content
# NOTE at this point, excerpt is already set to an instance of Jekyll::Excerpt unless set in front matter
if ::Jekyll::Page === document || !(::Jekyll::Excerpt === document.data['excerpt'])
header = '' unless HeaderLineRx.match? header
else
document.data['excerpt'] = nil
if (excerpt_separator = document.data['excerpt_separator'] || @asciidoc_config['excerpt_separator'] ||
@config['excerpt_separator']).to_s.empty?
header = '' unless HeaderLineRx.match? header
else
header_boundary = 0 unless header_boundary && (HeaderLineRx.match? header)
if (excerpt_boundary = content.index excerpt_separator, header_boundary)
header = content.slice 0, excerpt_boundary
else
header = content
end
end
end
header
else
''
end
end
def symbolize_keys hash
hash.each_with_object({}) {|(key, val), accum| accum[key.to_sym] = val }
end
def compile_attributes attrs, initial = {}
if (is_array = ::Array === attrs) || ::Hash === attrs
attrs.each_with_object(initial) do |entry, new_attrs|
key, val = is_array ? (((entry.split '=', 2) + ['', '']).slice 0, 2) : entry
if key.start_with? '!'
new_attrs[key.slice 1, key.length] = nil
elsif key.end_with? '!'
new_attrs[key.chop] = nil
# we're reserving -name to mean "unset implicit value but allow doc to override"
elsif key.start_with? '-'
new_attrs.delete key.slice 1, key.length
else
case val
when ::String
new_attrs[key] = resolve_attribute_refs val, new_attrs
when ::Numeric
new_attrs[key] = val.to_s
when true
new_attrs[key] = ''
when nil, false
# we may preserve false in the future to mean "unset implicit value but allow doc to override"
# false already has special meaning for page-layout, so don't coerce it
new_attrs[key] = key == 'page-layout' ? val : nil
else
new_attrs[key] = val
end
end
end
else
initial
end
end
def resolve_attribute_refs text, attrs
if text.empty?
text
elsif text.include? '{'
text.gsub AttributeReferenceRx do
($&.start_with? '\\') ? ($&.slice 1, $&.length) : ((attrs.fetch $1, $&).to_s.chomp '@')
end
else
text
end
end
def resolve_default_layout document, attributes
layout_attr_name = %(#{@asciidoc_config['page_attribute_prefix']}layout)
if attributes.key? layout_attr_name
if ::String === (layout = attributes[layout_attr_name])
if layout == '~@'
layout = 'none@'
elsif (layout.end_with? '@') && ((document.data.key? 'layout') || document.data['layout'])
layout = %(#{(layout = document.data['layout']).nil? ? 'none' : layout}@)
else
layout = nil
end
elsif layout.nil?
layout = 'none'
else
layout = layout.to_s
end
elsif (document.data.key? 'layout') || document.data['layout']
layout = %(#{(layout = document.data['layout']).nil? ? 'none' : layout}@)
else
layout = '@'
end
layout ? { layout_attr_name => layout } : nil
end
# Register pre and post render callbacks for saving and clearing contextual AsciiDoc attributes, respectively.
::Jekyll::Hooks.tap do |hooks|
hooks.register [:pages, :documents], :pre_render, &(method :before_render)
hooks.register [:pages, :documents], :post_render, &(method :after_render)
end
end
end
end
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/core_ext.rb 0000664 0000000 0000000 00000000054 14522137003 0022526 0 ustar 00root root 0000000 0000000 require_relative 'core_ext/regexp/is_match'
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/core_ext/ 0000775 0000000 0000000 00000000000 14522137003 0022202 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/core_ext/regexp/ 0000775 0000000 0000000 00000000000 14522137003 0023474 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/core_ext/regexp/is_match.rb 0000664 0000000 0000000 00000000213 14522137003 0025604 0 ustar 00root root 0000000 0000000 # NOTE remove once minimum required Ruby version is at least 2.4
class Regexp
alias match? ===
end unless Regexp.method_defined? :match?
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/excerpt.rb 0000664 0000000 0000000 00000003020 14522137003 0022364 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
class Excerpt < ::Jekyll::Excerpt
if Jekyll3_0
def_delegators :@doc, :destination, :url
else
def_delegators :@doc, :destination
end
def initialize primary_doc, excerpt_content
excerpt_doc = primary_doc.dup
excerpt_doc.content = excerpt_content
excerpt_doc.extend NoLiquid unless primary_doc.data['liquid']
super excerpt_doc
end
def extract_excerpt content
# NOTE excerpt_doctype has already been resolved from either the page attribute or front matter variable
if (doctype = (excerpt_data = data)['excerpt_doctype'] ||
(inherited = doc.site.config['asciidoc']['excerpt_doctype']))
excerpt_data['doctype'] = doctype
excerpt_data['excerpt_doctype'] = doc.data['excerpt_doctype'] = doctype if inherited
end
content
end
def output
unless defined? @output
renderer = ::Jekyll::Renderer.new doc.site, self, site.site_payload
@output = renderer.run
trigger_hooks :post_render
end
@output
end
def render_with_liquid?
!(NoLiquid === doc)
end
# NOTE Jekyll 3.0 incorrectly maps to_liquid to primary doc
alias to_liquid data if Jekyll3_0
def trigger_hooks hook_name, *args
#::Jekyll::Hooks.trigger collection.label.to_sym, hook_name, self, *args if collection
::Jekyll::Hooks.trigger :documents, hook_name, self, *args
end
end
end
end
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/filters.rb 0000664 0000000 0000000 00000003156 14522137003 0022374 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
module Filters
# A Liquid filter for converting an AsciiDoc string to HTML using {Converter#convert}.
#
# @param input [String] the AsciiDoc String to convert.
# @param doctype [String] the target AsciiDoc doctype.
#
# @example Convert the AsciiDoc page excerpt to inline HTML
# {{ page.excerpt | asciidocify: 'inline' }}
#
# @return [String] the converted result as an HTML-formatted String.
def asciidocify input, doctype = nil
(@context.registers[:cached_asciidoc_converter] ||= (Converter.get_instance @context.registers[:site]))
.convert(doctype ? %(:doctype: #{doctype}#{Utils::NewLine}#{input}) : (input || ''))
end
# A Liquid filter for generating an HTML table of contents from a parsed AsciiDoc document.
#
# @param document [Asciidoctor::Document] the parsed AsciiDoc document for which to generate an HTML table of
# contents.
# @param levels [Integer] the maximum section depth to use; if not specified, uses the value of toclevels document
# attribute.
#
# @example Generate a table of contents from the document for the current page
# {{ page.document | tocify_asciidoc: 3 }}
#
# @return [String] the table of contents as an HTML-formatted String.
def tocify_asciidoc document, levels = nil
::Asciidoctor::Document === document ?
(document.converter.convert document, 'outline', toclevels: (levels.nil_or_empty? ? nil : levels.to_i)) : nil
end
end
::Liquid::Template.register_filter Filters
end
end
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/integrator.rb 0000664 0000000 0000000 00000015151 14522137003 0023100 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
# Promotes eligible AsciiDoc attributes to page variables and applies page-level settings to all documents handled
# by the converter included with this plugin. It also copies the custom Pygments stylesheet if Pygments is the
# source highlighter and configured to use class-based styling.
class Integrator < ::Jekyll::Generator
NewLine = Utils::NewLine
PygmentsRootSelector = /^(.+?)\.pygments +{/
# Enable plugin when running in safe mode; jekyll-asciidoc gem must also be declared in whitelist
safe true
def self.get_instance site
site.find_generator_instance self
end
# This method is triggered each time the site is generated, including after any file has changed when running in
# watch mode (regardless of incremental setting).
#
# @param site [Jekyll::Site] the site being processed.
#
# @return [nil] Nothing
def generate site
@converter = converter = Converter.get_instance site
site.pages.select! do |page|
(converter.matches page.ext) ? (integrate page) : true
end
site.collections.each do |name, collection|
collection.docs.select! do |doc|
(converter.matches doc.extname) ? (integrate doc, name) : true
end
end
if site.config['asciidoc']['processor'] == 'asciidoctor'
attrs = site.config['asciidoctor'][:attributes]
attrs['localdate'], attrs['localtime'] = (site.time.strftime '%Y-%m-%d %H:%M:%S %Z').split ' ', 2
if ((attrs['source-highlighter'] || '').chomp '@') == 'pygments' &&
((attrs['pygments-css'] || '').chomp '@') != 'style' && (attrs.fetch 'pygments-stylesheet', '')
generate_pygments_stylesheet site, attrs
end
end
nil
end
# Integrate the page-related attributes from the AsciiDoc document header into the data Array of the specified
# {::Jekyll::Page}, {::Jekyll::Post} or {::Jekyll::Document}.
#
# @param document [::Jekyll::Page, ::Jekyll::Post, ::Jekyll::Document] the page, post, or document to integrate.
# @param collection_name [String] the name of the collection to which this document belongs.
#
# @return [Boolean] whether the document should be published.
def integrate document, collection_name = nil
return true unless (doc = @converter.load_header document)
data = document.data
data['asciidoc'] = true
# NOTE id is already reserved in Jekyll for another purpose, so we'll map id to docid instead
data['docid'] = doc.id if doc.id
data['title'] = doc.doctitle if doc.header?
data['author'] = doc.author if doc.author
if collection_name && (doc.attr? 'revdate')
data['date'] = ::Jekyll::Utils.parse_date doc.revdate,
%(Document '#{document.relative_path}' does not have a valid revdate in the AsciiDoc header.)
end
page_attr_prefix = document.site.config['asciidoc']['page_attribute_prefix']
no_prefix = (prefix_size = page_attr_prefix.length) == 0
adoc_data = doc.attributes.each_with_object({}) do |(key, val), accum|
if no_prefix || ((key.start_with? page_attr_prefix) && (key = key[prefix_size..-1]))
accum[key] = ::String === val ? (parse_yaml_value val) : val
end
end
data.update adoc_data unless adoc_data.empty?
{ 'category' => 'categories', 'tag' => 'tags' }.each do |sole_key, coll_key|
if (sole_val = data[sole_key])
(coll_val = data[coll_key] ||= []).delete sole_val
coll_val.unshift sole_val
elsif (coll_val = data[coll_key])
data[sole_key] = coll_val[0]
end
end
# NOTE excerpt must be set before layout is assigned since excerpt cannot have a layout (or be standalone)
unless ::Jekyll::Page === document
data['excerpt'] = Excerpt.new document, ((excerpt = data['excerpt']) || doc.source)
data['excerpt_origin'] = excerpt ? ((adoc_data.key? 'excerpt') ? 'asciidoc-header' : 'front-matter') : 'body'
end
case data['layout']
when nil
data['standalone'] = true unless data.key? 'layout'
when '', '_auto'
layout = collection_name ? (collection_name.chomp 's') : 'page'
data['layout'] = (document.site.layouts.key? layout) ? layout : 'default'
when false
data['layout'] = 'none'
data['standalone'] = true
end
document.extend Document
document.extend NoLiquid unless data['liquid']
data.fetch 'published', true
end
def generate_pygments_stylesheet site, attrs
css_base = site.source
unless (css_dir = (attrs['stylesdir'] || '').chomp '@').empty? || (css_dir.start_with? '/')
css_dir = %(/#{css_dir})
end
css_name = attrs['pygments-stylesheet'] || 'asciidoc-pygments.css'
css_file = ::File.join css_base, css_dir, css_name
css_style = (attrs['pygments-style'] || 'vs').chomp '@'
css = ::Asciidoctor::Stylesheets.instance.pygments_stylesheet_data css_style
# NOTE apply stronger CSS rule for general text color
css = css.sub PygmentsRootSelector, '\1.pygments, \1.pygments code {'
if site.static_files.any? {|f| f.path == css_file }
::File.write css_file, css unless css == (::File.read css_file)
else
::FileUtils.mkdir_p ::File.dirname css_file
::File.write css_file, css
site.static_files << (::Jekyll::StaticFile.new site, css_base, css_dir, css_name)
end
end
private
# Parse the specified value as though it is a single-line value part of a YAML key/value pair.
#
# Attempt to parse the specified String value as though it is a single-line value part of a YAML key/value pair.
# If the value fails to parse, wrap the value in single quotes (after escaping any single quotes in the value) and
# parse it as a character sequence. If the value is empty, return an empty String.
#
# @param val [String] the value to parse.
#
# @return [Object, String] the value parsed from the string-based YAML value or an empty String if the specified
# value is empty.
def parse_yaml_value val
if val.empty?
''
else
begin
::SafeYAML.load %(--- #{val})
rescue ::StandardError, ::SyntaxError
val = val.gsub '\'', '\'\'' if val.include? '\''
::SafeYAML.load %(--- \'#{val}\')
end
end
end
end
end
end
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext.rb 0000664 0000000 0000000 00000000223 14522137003 0023066 0 ustar 00root root 0000000 0000000 require_relative 'jekyll_ext/drops/drop'
require_relative 'jekyll_ext/renderer/layouts'
require_relative 'jekyll_ext/site/find_generator_instance'
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/ 0000775 0000000 0000000 00000000000 14522137003 0022544 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/drops/ 0000775 0000000 0000000 00000000000 14522137003 0023673 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/drops/drop.rb 0000664 0000000 0000000 00000000561 14522137003 0025166 0 ustar 00root root 0000000 0000000 module Jekyll
module Drops
class Drop
class << self
# NOTE fixes "warning: instance variable @is_mutable not initialized"
prepend (Module.new do
def mutable?
@is_mutable ||= nil # rubocop:disable Naming/MemoizedInstanceVariableName
end
end)
end
end
end
end if defined? Jekyll::Drops::Drop
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/renderer/ 0000775 0000000 0000000 00000000000 14522137003 0024352 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/renderer/layouts.rb 0000664 0000000 0000000 00000000433 14522137003 0026377 0 ustar 00root root 0000000 0000000 module Jekyll
class Renderer
# NOTE fixes "warning: instance variable @layouts not initialized"
prepend (Module.new do
def layouts
@layouts = nil unless defined? @layouts
super
end
end)
end
end if Jekyll::Renderer.method_defined? :layouts
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/site/ 0000775 0000000 0000000 00000000000 14522137003 0023510 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/jekyll_ext/site/find_generator_instance.rb 0000664 0000000 0000000 00000000514 14522137003 0030707 0 ustar 00root root 0000000 0000000 module Jekyll
class Site
# Introduce complement to {::Jekyll::Site#find_converter_instance} for generators.
def find_generator_instance type
generators.find {|candidate| type === candidate } || (raise %(No Generators found for #{type}))
end
end
end unless Jekyll::Site.method_defined? :find_generator_instance
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/mixins.rb 0000664 0000000 0000000 00000000401 14522137003 0022221 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
Configured = ::Module.new
Document = ::Module.new
module Liquidable
def to_liquid
self
end
end
module NoLiquid
def render_with_liquid?
false
end
end
end
end
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/utils.rb 0000664 0000000 0000000 00000002002 14522137003 0022051 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
module Utils
MessageTopic = 'Jekyll AsciiDoc:'
NewLine = ?\n
module_function
# Checks whether the file at the specified path has front matter. For AsciiDoc files, this method always returns
# true. Otherwise, it delegates to {::Jekyll::Utils.has_yaml_header?}.
#
# @param dlg_method [Method] the delegate method to call if this path is not an AsciiDoc file.
# @param asciidoc_ext_rx [Regexp] the regular expression to use to check if this path is an AsciiDoc file.
# @param path [String] the path to check.
#
# @return [Boolean] whether the file at this path has front matter.
def has_front_matter? dlg_method, asciidoc_ext_rx, path
(asciidoc_ext_rx.match? ::File.extname path) || (dlg_method.call path)
end
# NOTE use define_method to match signature of original method (and avoid extra call)
define_method :has_yaml_header?, &(::Jekyll::Utils.method :has_yaml_header?)
end
end
end
jekyll-asciidoc-3.0.1/lib/jekyll-asciidoc/version.rb 0000664 0000000 0000000 00000000100 14522137003 0022373 0 ustar 00root root 0000000 0000000 module Jekyll
module AsciiDoc
VERSION = '3.0.1'
end
end
jekyll-asciidoc-3.0.1/release.sh 0000775 0000000 0000000 00000003352 14522137003 0016540 0 ustar 00root root 0000000 0000000 #!/bin/bash
# required packages (for ubuntu:kinetic): curl git jq ruby
if [ -z "$RELEASE_RUBYGEMS_API_KEY" ]; then
echo No API key specified for publishing to rubygems.org. Stopping release.
exit 1
fi
export RELEASE_BRANCH=${GITHUB_REF_NAME:-main}
if [ ! -v RELEASE_USER ]; then
export RELEASE_USER=$GITHUB_ACTOR
fi
RELEASE_GIT_NAME=$(curl -s https://api.github.com/users/$RELEASE_USER | jq -r .name)
RELEASE_GIT_EMAIL=$RELEASE_USER@users.noreply.github.com
GEMSPEC=$(ls -1 *.gemspec | head -1)
RELEASE_GEM_NAME=$(ruby -e "print (Gem::Specification.load '$GEMSPEC').name")
# RELEASE_VERSION must be an exact version number; if not set, defaults to next patch release
if [ -z "$RELEASE_VERSION" ]; then
export RELEASE_VERSION=$(ruby -e "print (Gem::Specification.load '$GEMSPEC').version.then { _1.prerelease? ? _1.release.to_s : (_1.segments.tap {|s| s[-1] += 1 }.join ?.) }")
fi
export RELEASE_GEM_VERSION=${RELEASE_VERSION/-/.}
# configure git to push changes
git config --local user.name "$RELEASE_GIT_NAME"
git config --local user.email "$RELEASE_GIT_EMAIL"
# configure gem command for publishing
mkdir -p $HOME/.gem
echo -e "---\n:rubygems_api_key: $RELEASE_RUBYGEMS_API_KEY" > $HOME/.gem/credentials
chmod 600 $HOME/.gem/credentials
# release!
(
set -e
ruby tasks/version.rb
git commit -a -m "release $RELEASE_VERSION [no ci]"
git tag -m "version $RELEASE_VERSION" v$RELEASE_VERSION
mkdir -p pkg
gem build $GEMSPEC -o pkg/$RELEASE_GEM_NAME-$RELEASE_GEM_VERSION.gem
git push origin $(git describe --tags --exact-match)
gem push pkg/$RELEASE_GEM_NAME-$RELEASE_GEM_VERSION.gem
git push origin $RELEASE_BRANCH
)
exit_code=$?
# nuke gem credentials
rm -rf $HOME/.gem
# check for any uncommitted files
git status -s -b
exit $exit_code
jekyll-asciidoc-3.0.1/spec/ 0000775 0000000 0000000 00000000000 14522137003 0015510 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/spec/fixtures/ 0000775 0000000 0000000 00000000000 14522137003 0017361 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/spec/fixtures/alternate_page_attribute_prefix/ 0000775 0000000 0000000 00000000000 14522137003 0025774 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/spec/fixtures/alternate_page_attribute_prefix/_config.yml 0000664 0000000 0000000 00000000106 14522137003 0030120 0 ustar 00root root 0000000 0000000 plugins:
- jekyll-asciidoc
asciidoc:
page_attribute_prefix: jekyll-
jekyll-asciidoc-3.0.1/spec/fixtures/alternate_page_attribute_prefix/_layouts/ 0000775 0000000 0000000 00000000000 14522137003 0027633 5 ustar 00root root 0000000 0000000 jekyll-asciidoc-3.0.1/spec/fixtures/alternate_page_attribute_prefix/_layouts/default.html 0000664 0000000 0000000 00000000244 14522137003 0032145 0 ustar 00root root 0000000 0000000
{{ page.title }}