A plugin for Jekyll (>= 2.3.0) that converts the AsciiDoc source files in your site to HTML pages using Asciidoctor.
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, 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; only for Jekyll 3 or better and Asciidoctor).
-
These extensions are registered automatically when the jekyll-asciidoc gem is required.
This plugin is packaged as a gem named jekyll-asciidoc and published to RubyGems.org. The plugin depends on the 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.
If you’re using Bundler to manage the dependencies for your project (as recommended), simply add the jekyll-asciidoc gem to the :jekyll_plugins group in your Gemfile:
group :jekyll_plugins do
gem 'jekyll-asciidoc'
endThen, 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:
$ [sudo] gem install jekyll-asciidoc
|
📎
|
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 jekyll-asciidoc gem to the list of gems for Jekyll to load in your site’s _config.yml file:
gems:
- jekyll-asciidocThis 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 Configuration).
-
The name of the file must not begin with a dot (
.) or an underscore (_).[1] -
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).[1] -
(Optional beginning with version 2.0.0 of this plugin) Aside from posts, documents must begin with a front matter header.
Here’s a sample AsciiDoc file that meets these criteria:
---
layout: info
permalink: /sample/
---
= Sample Page
:uri-asciidoctor: http://asciidoctor.org
This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
[source,ruby]
puts "Hello, World!"Alternatively, you can define the page variables directly in the AsciiDoc header, which we recommend:
= Sample Page
:page-layout: info
:page-permalink: /sample/
:uri-asciidoctor: http://asciidoctor.org
This is a sample page composed in AsciiDoc.
Jekyll converts it to HTML using {uri-asciidoctor}[Asciidoctor].
[source,ruby]
puts "Hello, World!"AsciiDoc attributes defined in the AsciiDoc document header and whose name begins with page-[2] get promoted to 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 YAML data (single-line form).
|
❗
|
The AsciiDoc document header stops after the first blank line. You may use include directives in the the document header, but make sure the included file does not contain a blank line. |
|
💡
|
Use either a hyphen or an underscore as a separator for page attributes with multiple words (e.g., page-short-name). |
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 _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 _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 namedinfo(e.g., _layout/info.html) -
not specified,
:page-layout:or:page-layout: _auto— use the automatic layout (i.e.,pagefor pages,postfor posts, the singular form of the collection label for a document; if the auto-selected layout isn’t available, the layoutdefaultis used) -
:!page-layout:or:page-layout: false— don’t use a layout; instead, generate a standalone HTML document -
:page-layout: ~— don’t use a layout (often results in an incomplete HTML file)
In addition to page attributes defined explicitly, the following implicit AsciiDoc attributes are also promoted to page variables:
-
doctitle (aka the document title) (becomes title)
-
author
-
revdate (becomes date; value is converted to a DateTime object; posts only)
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:
= 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.
= Post Title
Author Name
2016-03-20 10h30m00s -0600
Lorem ipsum.Note that the revision line must be preceded by the implicit author line.
Unlike other content files, the Liquid template preprocessor is not applied to AsciiDoc files by default (as of 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).
:page-liquid:|
❗
|
AsciiDoc files may include a 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). |
|
📎
|
As of 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. |
You can build your site into the _site directory using:
$ jekyll build
If you’re using Bundler, prefix each command with bundle exec:
$ bundle exec jekyll build
You can preview your site at http://localhost:4000 using:
$ jekyll serve
Since Jekyll 2.4.0, the serve command monitors the file system and rebuilds the site whenever a change is detected by default (i.e., watch mode).
You can enable watch mode explicitly using the --watch flag:
$ jekyll serve --watch
To disable watch mode explicitly, use the --no-watch flag instead.
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
|
❗
|
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 Running in Safe Mode for details.
|
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 _config.yml, respectively, if you don’t plan on making any further customizations.
asciidoc: {}
asciidoctor: {}Using these placeholder values prevents initialization from being performed more than once when using watch mode (see issue jekyll#4858).
|
📎
|
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 _config.yml:
asciidoc:
processor: asciidoctor|
❗
|
The asciidoc block should only appear once inside _config.yml.
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 _config.yml:
asciidoc:
ext: asciidoc,adoc,adThe 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 _config.yml:
asciidoc:
page_attribute_prefix: jekyllA hyphen is automatically added to the value of this configuration setting if the value is non-empty.
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 _config.yml:
asciidoc:
require_front_matter_header: trueIn 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 attributes are defined per page:
outpath=(path of page relative to baseurl)
You can pass additional attributes to AsciiDoc, or override default attributes provided by the plugin, by using the attributes option of the asciidoctor block in your _config.yml.
The value of this option can either be an Array containing key-value pairs:
asciidoctor:
attributes:
- idprefix=_
- source-highlighter=pygments
- pygments-css=styleor key-value pairs defined as a Hash:
asciidoctor:
attributes:
idprefix: _
source-highlighter: pygments
pygments-css: styleWhen using the Hash syntax, you must use an empty string value to set a valueless attribute such as sectanchors:
asciidoctor:
attributes:
sectanchors: ''You may use attribute references in the attribute value to reference any implicit or already defined attribute.
For example, to set the iconsdir attribute based on the imagesdir attribute, use the following:
asciidoctor:
attributes:
imagesdir: /images
iconsdir: '{imagesdir}/icons'|
🔥
|
If the value begins with an attribute reference, and you’re defining the attributes using the Hash structure, you must enclose the value in quotes. Beware that there are additional edge cases when the value must be enclosed in quotes. |
Since version 2.1.0 of this plugin, you can remove a previously defined attribute by prefixing the name with a hyphen (aka minus):
asciidoctor:
attributes:
-idprefix:In addition to attributes, you may define any other option key (e.g., safe) recognized by the Asciidoctor API.
One of those is base_dir, which is covered in the next section.
In Asciidoctor, the base directory (i.e., base_dir option) is used as the root when resolving non-nested, relative includes, among other paths.
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.
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.
Since the base directory is also the jail, we also recommend setting the safe option to unsafe so that you can still resolve paths outside of this directory.
asciidoctor:
base_dir: :docdir
safe: unsafe
...|
❗
|
The :docdir setting is not available when using Jekyll 2.
|
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.
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-option attribute to the Asciidoctor attributes configuration in your site’s _config.yml file:
asciidoctor:
attributes:
- hardbreaks-optionIf you want to allow individual files to override this setting, then assign the value @ to the attribute:
asciidoctor:
attributes:
- hardbreaks-option=@If you already have AsciiDoc attributes defined in the _config.yml, the new attribute should be added as a sibling entry in the YAML collection.
|
|
Keep in mind, if you enable hard line breaks, you won’t be able to use the one sentence-per-line writing technique. |
If you want to use this plugin when running Jekyll in safe mode, you must add the jekyll-asciidoc gem to the whitelist in your site’s _config.yml file:
whitelist:
- jekyll-asciidocSafe mode is enabled either through the --safe flag:
$ jekyll build --safe
or the safe configuration option in your site’s _config.yml file:
safe: trueJekyll 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.
You can use the asciidocify filter to convert an arbitrary AsciiDoc string anywhere in your template.
Let’s assume the excerpt of the post is written in AsciiDoc. You can convert it in your template as follows:
{{ post.excerpt | asciidocify }}
By default, the AsciiDoc content is parsed as a full 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:
{{ post.excerpt | asciidocify: 'inline' }}
|
💡
|
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). |
Since version 2.1.0 of this plugin, if you’re using Jekyll 3 or better, 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.
= Guide
:toc: left
== Section A
content
== Section B
contentYou 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 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.
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.
gem 'slim', '~> 3.0.7'
gem 'thread_safe', '~> 0.3.5'Next, create a new folder in your site named _templates to store your templates.
$ mkdir _templates
In your site’s _config.yml file, configure Asciidoctor to load the templates by telling it the location where the templates are stored.
asciidoctor:
template_dir: _templates
attributes: ...The final step is to compose a template. We’ll be customizing the unordered list node. Name the file ulist.html.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.contentThe next time you build your site, Asciidoctor will use your custom template to generate the HTML for unordered lists.
|
💡
|
You can find additional examples of custom templates in the asciidoctor-backends repository. |
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 Jekyll >= 3.0.0 and a version of this plugin >= 2.0.0. Other combinations are known to have issues.
|
❗
|
For Graphviz and PlantUML diagram generation, Graphviz must be installed (i.e., the dot utility must be available on your $PATH.
|
- Using Bundler
-
Add
asciidoctor-diagramgem to your Gemfile:group :jekyll_plugins do gem 'asciidoctor-diagram', '~> 1.4.0' # # (1) gem 'jekyll-asciidoc' ... end
-
Customize the version of Asciidoctor Diagram as needed.
Then, run Bundler’s install command to install the new gem:
$ bundle install
-
- Without Bundler
-
Install gems manually
$ [sudo] gem install asciidoctor-diagram
Then, add the
asciidoctor-diagramgem to the list of gems for Jekyll to load in your site’s _config.yml file:gems: - asciidoctor-diagram - jekyll-asciidoc
The preceding configurations are equivalent to passing -r asciidoctor-diagram to the asciidoctor command.
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 _config.yml:
asciidoctor:
base_dir: :docdir
safe: unsafeWith this configuration, Asciidoctor Diagram will generate images relative to the generated HTML page (i.e., into the same directory).
You can use the following example to test your setup:
= 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:
asciidoctor:
base_dir: :docdir
safe: unsafe
attributes:
imagesdir: /imagesWith this configuration, all images will be generated into the images directory inside the destination folder.
Since Asciidoctor Diagram writes to the output folder, you have to instruct Jekyll not to remove these generated files. One way to do this is to apply a “monkeypatch” to Jekyll. Add the file jekyll-ext.rb to the _plugins folder of your project root (creating the folder if it does not already exist) and populate the file with the following content:
class Jekyll::Cleaner
def cleanup!; end
endAn alternative to the monkeypath approach is to identify folders that contain generated images in the keep_files option in _config.yml:
keep_files: [images]
asciidoctor:
base_dir: :docdir
safe: unsafe
attributes:
imagesdir: /imagesCertain 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.
|
💡
|
If you want to take a shortcut that skips all this configuration, clone the 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. |
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 css directory named asciidoc.css to hold additional CSS for body content generated from AsciiDoc.
-
Add this stylesheet to the HTML
<head>in _includes/head.html under the main.css declaration:<link rel="stylesheet" href="{{ "/css/asciidoc.css" | prepend: site.baseurl }}">
Asciidoctor integrates with Pygments to provide code highlighting of source blocks in AsciiDoc content. This integration is separate from the Pygments integration in Jekyll. 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 _config.yml are configured as follows:
-
source-highlighterhas the valuepygments -
pygments-csshas the valueclassor is not set -
pygments-stylesheetis not unset (if set, it can have any value)
By default, the stylesheet is written to stylesdir + pygments-stylesheet.
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, such as:
<link rel="stylesheet" href="{{ "/css/asciidoc-pygments.css" | prepend: site.baseurl }}">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 _config.yml.
|
📎
|
It may still be necessary to make some tweaks to your site’s stylesheet to accomodate this integration. |
To enable font-based admonition and inline icons, you first need to add Font Awesome to _includes/head.html file under the asciidoc.css declaration:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css">|
📎
|
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 css/asciidoc.css file:
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:
:icons: fontor in the site configuration:
asciidoctor:
attributes:
- icons=font
...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:
:icons:
:iconsdir: /images/iconsor your site configuration:
asciidoctor:
attributes:
- icons
- iconsdir=/images/iconsThen, simply put the icon images that the page needs in the images/icons directory.
This section covers several options you have available for publishing your site, including GitHub Pages and GitLab 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.
|
❗
|
GitHub needs to hear from enough users that need this plugin to persuade them to enable it. Our recommendation is to contact support and keep asking for it. Refer to the help page 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 Automate GitHub Pages publishing with Jekyll and Travis CI tutorial to find step-by-step instructions. You can also refer to the Transfuse website build for an example in practice.
|
💡
|
When using this setup, don’t forget to add the .nojekyll file to the root of the source to tell GitLab Pages not to waste time running Jekyll again on the server. |
If you want to take a shortcut that skips all the steps in the previously mentioned tutorial, clone the 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.
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 Hosting on GitLab.com with GitLab Pages.
Assuming the following are true:
-
The source of your site resides on the master branch.
-
You’re using Bundler to manage the dependencies for your project.
then you can use the following .gitlab-ci.yml file to get starting hosting your Jekyll site on GitLab Pages.
image: ruby:2.3
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:
- masterThis script runs Jekyll on the official Ruby Docker container.
You also need to add an additional configuration file, _config-gitlab.yml, to set the url and baseurl options when deploying your site to GitLab Pages.
url: https://<username>.gitlab.io # # (1)
baseurl: /<projectname> # # (2)-
Replace
<username>with your GitLab username or group. -
Replace
<projectname>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 https://<username>.gitlab.io/<projectname>, where <username> is your GitLab username or group and <projectname> 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 _config-gitlab.yml file with the appropriate values.
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 Jekyll website. If you have general questions about Jekyll, we recommend you visit the Jekyll Talk forum to get assistance. For questions related to this extension specifically, or general questions about AsciiDoc, please post to the Asciidoctor discussion list. You can also join us in the asciidoctor/asciidoctor channel on Gitter. For general information about AsciiDoc, look no further than the Asciidoctor User Manual.
This project uses the GitHub issue tracker to manage bug reports and feature requests. If you encounter a problem, please browse or search the issues to find out if your problem has already been reported. If it has not, you may 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.
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.
You can retrieve the source code from GitHub using git.
Simply copy the URL of the GitHub repository and pass it to the git clone command:
git clone https://github.com/asciidoctor/jekyll-asciidoc
Next, switch to the project directory.
$ cd jekyll-asciidoc
The dependencies needed to develop the Jekyll AsciiDoc plugin are defined in the 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
|
❗
|
Since we’ve installed dependencies inside the project, it’s necessary to prefix all commands (e.g., rake) with bundle exec.
|
The tests are based on RSpec. The test suite is located in the 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:
it 'should register AsciiDoc converter', focus: true do
expect(site.converters.any? {|c| ::Jekyll::AsciiDoc::Converter === c }).to be true
endThen, 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.
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 in your site. If you want to build the gem and install it manually, use these commands instead:
$ bundle exec rake build $ [sudo] gem install pkg/jekyll-asciidoc-*.dev.gem
This project adheres to the coding style used throughout the Asciidoctor project. The coding style is 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).
-
Don’t indent
whenlines in a case block. -
Wrap API docs at 120 characters.
-
Leave a single space inside brackets of a Hash.
{ "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
-
For chained method calls, wrap parentheses around nested method call.
asciidoctor_config.replace (Utils.symbolize_keys asciidoctor_config)
-
Add
%rprefix 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 parantheses around a variable assignment inside a condition.
if (imagesdir = attrs['imagesdir'])
-
Use simple 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)
-
Store each static regular expression in a constant. Add
Rxsuffix to name.HeaderBoundaryRx = /(?<=\p{Graph})\n\n/ -
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('<div class="page-content">')
When you are ready for a release, first set the version in the file 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
|
❗
|
Ensure you have the proper credentials setup as described in the guide 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., 2.0.1.dev).
The Jekyll AsciiDoc plugin, a plugin for the static site generator Jekyll, is a member project of the Asciidoctor organization. This plugin is developed and supported by volunteers in the Asciidoctor community.
This plugin was created by Dan Allen and Paul Rayner and has received contributions from many other individuals in the Asciidoctor community.
Copyright © 2013-2016 Dan Allen, Paul Rayner, and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License. See LICENSE for details.