Link Search Menu Expand Document
Consortium of European Social Science Data Archives

Documentation Tooling

To generate static documentation pages, including this one, CESSDA uses Jekyll. A custom CESSDA theme has been developed based on the Just the docs theme.

As such, the documentation for Just the docs can be followed, but the design should not be touched.

The repository for the CESSDA Technical Guidelines should be consulted for implementation details. The repository’s README also lists a number of recommendations on language.

Using the CESSDA theme

To use the CESSDA theme, install the Ruby gem jekyll-cessda-docs, e.g. with a Gemfile:

source 'https://rubygems.org'
gem 'jekyll-cessda-docs'
gem 'html-proofer'
gem 'mdl'
gem 'rake'

Then make sure to specify the theme in your _config.yml

theme: jekyll-cessda-docs

To get started locally, make sure to have Ruby installed, then run

gem install jekyll bundler
bundle install
bundle exec jekyll serve

Just the docs support

You can use most of the functionalities of Just the docs, in particular search.

Matomo

The theme allows to enable support for CESSDA’s Matomo through a _config.yml setting

matomo_siteid: '0'

The siteid must be registered in Matomo first and configured to only accept the correct domains.

CESSDA Technical Guidelines

For the CESSDA Technical Guidelines a glossary functionality has been added. Glossary entries must be added to _data/glossary.yml and referenced using

{% include glossary.html entry="RI" text="RI" %}

Note that glossary entries have to be referenced with exact matching, including case. It is possible to display a different text in-line though:

{% include glossary.html entry="RI" text="Research Infrastructure" %}

Also, always make sure to run the local instance with

bundle exec jekyll serve --config _config.yml,_devsettings.yml

Quality measures

Markdown linting

CESSDA uses mdl for Markdown linting (included with the above Gemfile) with the following configuration

  • .mdl.style
all
rule 'MD003', :style => :atx
rule 'MD009', :br_spaces => 2
rule 'MD013', :line_length => 140, :tables => false
  • .mdlrc
style File.join(File.dirname(__FILE__), '.mdl.style')
ignore_front_matter true

HTML checking

CESSDA uses html-proofer to verify the output.

Rakefile

The following Rakefile defines the jobs

  • bundle exec rake lint
  • bundle exec rake htmlproofer

Rakefile

require 'html-proofer'

task default: %w[lint]

task :lint do
  exec 'find . -name "*.md" | grep -v "^.\/vendor\/" | xargs mdl'
end

task :htmlproofer do
  options = { :only_4xx => true, :allow_hash_href => true }
  HTMLProofer.check_directory("./_site", options).run
end