Skip to content

Modules

Jump to bottom
Ruben Taelman edited this page Dec 6, 2019 · 19 revisions

ScholarMarkdown consists of several modules that can be used to write your articles.

It is based on nanoc filters and preprocessors, which can be enabled or disabled in your Rules file.

This is an example of how these modules can be configured:

require 'scholarmarkdown/preprocess/katex'
require 'scholarmarkdown/filter/acronym'
require 'scholarmarkdown/filter/citation'
require 'scholarmarkdown/filter/hyphenate_iri'
require 'scholarmarkdown/filter/include_code'
require 'scholarmarkdown/filter/labelify'
require 'scholarmarkdown/filter/references_to_footer'
require 'scholarmarkdown/filter/headerids_to_section'
require 'scholarmarkdown/filter/dokieli_ui'
require 'scholarmarkdown/filter/annotations'
require 'scholarmarkdown/filter/citation_metadata'

preprocess do
  # Enables math-mode
  preprocess_katex_assets
end

compile '/index.*' do
  filter :erb
  filter :scholar_citation, bibfile: items['/references.bib'],
                            style: 'lncs-custom'
  filter :kramdown, math_engine: 'sskatex',
                    math_engine_opts: {
                      :katex_js=> File.join(Katex.gem_path, 'vendor', 'katex', 'javascripts', 'katex.js')
                    }
  filter :scholar_acronym, acronyms: items['/acronyms.csv']
  filter :scholar_hyphenate_iri
  filter :scholar_include_code
  filter :scholar_labelify
  filter :scholar_references_to_footer
  filter :scholar_headerids_to_section
  filter :rubypants
  layout '/default.*'
  filter :scholar_dokieli_ui
  filter :scholar_annotations, notifications: '...',
                               annotations: '...'
  filter :scholar_citation_metadata, publication_date: '2019/01/01',
                                     journal_title: 'Journal of Web Semantics',
                                     volume: '54',
                                     issue: '1',
                                     firstpage: '4',
                                     lastpage: '28',
                                     doi: '10.1016/j.websem.2018.08.001'
end

Note that most filters must be added before the layout line, unless otherwise noted.

All available modules are listed below.

Math mode

LaTeX math equations are one of the most powerful ways to write mathematical equations. Using the power of KaTeX and SsKaTeX, LaTeX equations can be written directly within your markdown documents, and they will be displayed as nice equations.

Usage

require 'scholarmarkdown/preprocess/katex'

preprocess do
  preprocess_katex_assets
end

compile '/index.*' do
  ...
  filter :kramdown, math_engine: 'sskatex',
                    math_engine_opts: {
                      :katex_js=> File.join(Katex.gem_path, 'vendor', 'katex', 'javascripts', 'katex.js')
                    }
  ...
  layout '/default.*'
  ...
end

After that, you will be able to write equations as explained in Snippets - Math equations.

Usage

Acronym

Usage

acronyms.csv (name can be changed) must exist in your content/ folder. It must have two columns: abbreviation and full.

Example of an acronyms file:

abbreviation,full
HTTP,Hypertext Transfer Protocol
RDF,Resource Description Framework

require 'scholarmarkdown/filter/acronym'

filter :scholar_acronym, acronyms: items['/acronyms.csv']

List of acronyms

Optionally, a list of acronyms can be displayed in a table by including <div id="scholarmarkdown-acronyms-list"></div> in your document.

Citation

Define citations using BibMarkdown.

This allows you to make citations in Markdown as follows: [Semantic Web](cite:cites semanticweb).

Usage

references.bib (name can be changed) must exist in your content/ folder. This file must be a BibTex file.

require 'scholarmarkdown/filter/citation'

filter :scholar_citation, bibfile: items['/references.bib'],
                          style: 'lncs-custom'

Citation metadata

Certain services like Google Scholar crawl the Web to find scholarly articles. In order to be indexed by these services, you have to add certain meta tags into your HTML.

For this, ScholarMarkdown provides a filter (enabled by default since version 2.3.0) that emits all required metadata for getting indexed into Google Scholar. Optionally, you can provide additional parameters.

The following meta values will or can be emitted:

Name Required Description
title (automatic) Yes The full article title
author (automatic) Yes All authors of the article
publication_date (automatic) Yes The publication date of the article. By default, this will correspond to the last article update, but can be overridden via the parameters in the Rules file.
journal_title No The full name of the journal
volume No The journal volume number
issue No The journal issue number
firstpage No The starting page in the journal
lastpage No The last page in the journal
doi No The DOI of the article

Usage

Basic form without parameters (enabled by default since version 2.3.0):

require 'scholarmarkdown/filter/citation_metadata'

filter :scholar_citation_metadata

Form with all optional parameters:

require 'scholarmarkdown/filter/citation_metadata'

filter :scholar_citation_metadata, publication_date: '2019/01/01',
                                   journal_title: 'Journal of Web Semantics',
                                   volume: '54',
                                   issue: '1',
                                   firstpage: '4',
                                   lastpage: '28',
                                   doi: '10.1016/j.websem.2018.08.001'

Important: This filter must be defined after the layout definition.

Dokieli UI

Dokieli is an editor that allows people to add annotations and interact socially on articles.

This Dokieli module adds the required scripts and stylesheets to plug Dokieli into your article so that readers can use it without having to install anything.

Usage

require 'scholarmarkdown/filter/dokieli_ui'

filter ::scholar_dokieli_ui

Important: This filter must be defined after the layout definition.

Annotations and inbox links

This module adds the proper metadata to your document to enable people to annotate your article with comments, likes and so on. For this, you will need a notifications and annotations server, which can be any Linked Data Platform-compatible service, such as mayktso, trellis or solid.

When the Dokieli is enabled, annotations can be added via the UI.

Usage

Fill in your notifications and annotations URL.

require 'scholarmarkdown/filter/annotations'

filter ::scholar_annotations, notifications: 'my notifications inbox URL',
                              annotations: 'my annotations URL'

Important: This filter must be defined after the layout definition.

Header IDs to Section

Moves IDs on headings to their parent section.

require 'scholarmarkdown/filter/headerids_to_section'

filter :scholar_headerids_to_section

Hyphenate IRI

Hyphenate long IRIs.

This also enables links to be tagged with [My Link](http://example.org/){:.mandatory} so that they are always included in print-mode.

require 'scholarmarkdown/filter/hyphenate_iri'

filter :scholar_hyphenate_iri

Include Code

Includes code blocks from external files.

Example:

````/code/my-code-snippet.js````

This will include the contents from /content/code/my-code-snippet.js in a <pre /> tag.

require 'scholarmarkdown/filter/include_code'

filter :scholar_include_code

Labelify

Add labels to elements such as figures and sections, and make them referenceable.

Example:

<figure id="my-figure">
<img src="img/my-figure.svg" alt="[figure alt]">
<figcaption markdown="block">
Some caption
</figcaption>
</figure>

Have a look at my figure in [](#my-figure).

[](#my-figure) will be automatically replaced by Figure x.

You can add class="listing" to the <figure /> tag to make it a Listing instead of a Figure.

require 'scholarmarkdown/filter/labelify'

filter :scholar_labelify

Sections and chapters

By default, sections will be labeled as 'Section', 'Subsection', 'Subsubsection', ...

By setting the chapters parameter to true, these labels will become 'Chapter', 'Section', 'Subsection', ...

...
  filter :scholar_labelify, chapters: true
...

Table of Contents

This module allows you to insert <div id="scholarmarkdown-toc-index"></div> anywhere into your document to generate a table of contents from your present sections.

The output structure will look like this:

<ol class="index-entries index-entries-root" depth="0">
  <li><a href="#introduction" class="index-entry-name">Introduction</a>
      <ol class="index-entries" depth="1">
        <li><a href="#research-question" class="index-entry-name">Research Question</a>
        <li><a href="#hypotheses" class="index-entry-name">Hypotheses</a>
      </ol>
  </li>
</ol>

By default, this index will be hidden in screen-mode, and only shown in print-mode. This can be changed via CSS.

References to Footer

Moves the references section into <footer>.

require 'scholarmarkdown/filter/references_to_footer'

filter :scholar_references_to_footer
Clone this wiki locally