Installing Jekyll with AsciiDoc Support on Ubuntu Server 18.04 LTS
-
Ensure that Ubuntu’s software repositories are up to date
$ sudo apt update
-
Install essential software development tools
$ sudo apt install build-essential
-
Install Ruby and its development tools
$ sudo apt install ruby ruby-dev
-
Install AsciiDoctor
$ sudo gem install asciidoctor
-
Install Jekyll and Bundler
$ sudo gem install jekyll bundler
-
Create a Jekyll site using a name of your choice, e.g.
my-static-site
$ jekyll new my-static-site $ cd my-static-site
-
Edit the new site’s Gemfile for adding the
jekyll-asciidoc
plugin# If you have any plugins, put them here! group :jekyll_plugins do gem "jekyll-feed", "~> 0.6" gem "jekyll-asciidoc" gem "coderay" end
-
Edit the
_config.yml
file and add the following lines to configureasciidoctor
to usecoderay
for syntax highlighting of source code, scripts, and shell commandsasciidoctor: attributes: idprefix: _ icons: font source-highlighter: coderay coderay-css: style
-
Use Ruby
bundle
to install the new dependencies$ bundle install
-
Rebuild the site now that all dependencies have been installed
$ bundle exec jekyll build
-
Now the default CSS stylesheet has been generated, it needs the styles for the various admonition icons and access to Font Awesome, from which these icons are generated. First we need a copy of
_site/assets/main.css
because anything in the_site
branch of the Jekyll ecosystem will eventually get destroyed and recreated each time you rebuild the site usingbundle exec jekyll build
after adding or editing your content.$ mkdir assets $ cp _site/assets/main.css assets/.
-
Now that you have a new
assets
directory where you can add media, style sheets and other web assets that will not be overwritten or deleted by the build process, add this single line of code for the remote Font Awesome CSS styles and fonts to the top of themain.css
file.@import url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css');
-
According to the Jekyll-AsciiDoc documentation (see the Font-based Admonition and Inline Icons section), “you need to add the following CSS rules” for the admonition icons to appear. Placce them at the end of the
main.css
file.span.icon>.fa{cursor:default} a span.icon>.fa{cursor:inherit} .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}
-
Test the syntax highlighting of source code and admonition icon functionality by creating a test post (create a new file under
_posts
)= Test Jekyll-AsciiDoc Installation John Doe <[email protected]> :layout: post :experimental: true == New Section . Start of enumerated list * First item of a bulleted list * Another bulleted item . Test for source code syntax highlighting + [source,php] ---- <?php require_once 'Core.php'; $production = false; $core_object = new Core(); echo "Hello World<br />\n"; ?> ---- + . Test admonitions + [WARNING] ==== If you don`'t see an icon on the left, it didn`'t work! ==== + . End of tests.
-
Install any new plugins, rebuild the site, and start the Jekyll web server
$ bundle install $ bundle exec jekyll build $ bundle exec jekyll serve
If you are installing Jekyll on a remote host, start the Jekyll site with the IP address of your remote host, or better yet, have it listen on all available IP addresses of that host by appending
--host=0.0.0.0
to theserve
action:bundle exec jekyll serve --host=0.0.0.0
-
View your new Jekyll static site in a web browser: http://localhost:4000
Replace localhost with the hostname or domain name of your remote server if your Jekyll installation is not on your local workstation.