-
Notifications
You must be signed in to change notification settings - Fork 8
Awestruct 0.5.2 migration
jdf-site was built using awestruct since firsts versions (0.3, 0.4, …) but some changes on awestruct 0.5 caused the jdf-site to fail the build.
We needed to update jdf-site to use new awestruct otherwise the jdf-site could become too far from new awestruct version and could possibility become stuck on old versions.
The migration process described in this page has the finality to help others who needs to migrate also.
I hope that you enjoy and be helped.
-
Reduced environment setup through the use of Bundler
-
Changed asciidoc to asciidoctor
-
Use of Tilt to render files
-
Update bootstrap from 2.0.x to 2.3.x
-
Incorporate new features and extensions
For initial setup, the Gemfile was created using the dependency gems
source "https://rubygems.org" gem 'awestruct', '0.5.2' gem 'rdiscount', '~> 2.0.7', :platforms => [:ruby] gem 'htmlcompressor' gem 'coffee-script' gem 'uglifier' gem 'vpim' gem 'redcarpet' gem 'asciidoctor' gem 'coderay', '~> 1.0.9' gem 'rb-fsevent', '~> 0.9' gem 'hpricot'
The Rake file was copied from awestruct base_Rakefile. The task deploy was removed from Rakefile so we can continue to use the publish.sh script that we used previously to publish on Openshift, Staging and Production.
For some reason the _ext/identities.rb extension was not working properly. The identities.rb#lookup method had to be refactored.
A minor change was made on _ext/identities/github.rb but just to become aligned and similar to arquillian site
The major change on ruby code and extensions refers that now on awestruct there’s no Markdown and AsciiDoc Handler which make the existing code to extract asciidoc and markdown metadata to stop working. The solution was to move the extraction code from _ext/jdf.rb (AsciidocHandler#extract_metadata and MarkdownHandler#extract_metadata) to _ext/guide.rb (#extract_metadata_from_asciidoc and #extract_metadata_from_markdown)
The following snippet code shows how it is being used according to page.content_syntax
_ext/guide.rb
#extract metadata from different formats
if ( page.content_syntax == :asciidoc )
page.modified_content = extract_metadata_from_asciidoc(page, html)
elsif (page.content_syntax == :markdown)
page.modified_content = extract_metadata_from_markdown(page, html)
else
page.modified_content = page.content
end
As page.content is readonly, the modified content was placed on page.modified_content
The Lanyrd extension (_ext/lanyrd.rb) was using Hpricot to parse the html files. All references to Hpricot was removed and updated to Nokogiri.
Due to bootstrap migration and some css classes modifications, some changes had to be made on stylesheets/styles.scss - I believe that each site that is migrating needs to examine what changes are needed and there isn’t a general formula to migrate but you can check the changes needed on jdf-site here
When the asciidoc documents becomes rendered, the images was not being placed on where they were previously. For that reason, some changes have to made on _config/site.yaml to allow not only a correct link to the images but also to enable the code highlight.
_config_site.yml
asciidoctor:
:backend: html5
:attributes:
idprefix: ''
idseparator: '-'
imagesdir: ../
source-highlighter: coderay
coderay-css: style
The code highlight was made by Coderay as described as supported on asciidoctor documentation
The configuration to inform the code code highlighter was informed above, but it was also necessary to include the following snipped code to _layouts/base.html.haml
_layouts/base.html.haml
%style
- ::CodeRay::Encoders[:html]::CSS.new(:default).stylesheet
In jdf-site lifecycle, some extensions was created as it was not part of awestruct. Now, on awestruct 0.5.2 the following extensions are now part of it and were removed from jdf-site
Some old code like the class _ext/jdf.rb#Artifact was also removed.
-
jdf-site code is cleaner since some extensions are now builtin in Awestruct
-
environment setup reduced from 7 steps (install ruby, install some gems, install a javascript runtime, install asciidoc, install python eggs, install pygments, setup github auth) to 3 steps ( install ruby, run budler, setup github auth)
-
the build process is much more faster