mandarancio / scidown

SciDown processing library in C

Scidown

Scidown is a fork of Hoedown, a c Markdown parser and HTML and LaTeX generator. Scidown however it parse not only Markdown but also Scidown (yep same name) that support many features useful for scientific and scholar publishing.

For more information on the syntax and example look at the wiki.

More about the motivation and the planning of the project in the manifesto.

Features

• Integrated plot using charter and experimental support to gnuplot
• Figures, Tables and Listings with caption
• YAML header specify title, authors, css style, keywords and more
• Abstract syntax for defining abstracts
• Include external files include external files to build complex documents

Markdown Differences

A part of the extension added to the language there is only one difference in the output generated from scidown and hoedown of a standard markdown document:

• # title becomes <h2>title</h2> instead of <h1>
• ## subtitle becomes <h3>subtitle</h3> instead of <h2>
• well I suppose you get it all the headers are shifted of one

This is due the addition of the title information in form of YAML head as explained in the following section.

Compile and Run

To compile the project simply do the following:

git submodule update --init --recursive
mkdir build
cd build
meson ..
ninja

To install it simply run sudo ninja install inside the build folder. The executable scidown will be now available in the build folder, to use it simply:

scidown input.md
# print out the html or to save it
scidown input.md > output.html

Special Syntax

YAML Head

Is possible to add information and configuration in form of a YAML header:

---
title: your title
author: author 1
author: author 2
affiliation: affiliation
style: css file
keywords: list of keywords
numbering: true/false (number the chapters, sections and subsections)
---

Rest of your markdown file

the title, author and keywords will be used both as metadata of the html and displayed in the output.

External Files

Is possible to include external files to make easier work with big documents:

@include(path)

As bibliography only:

@bib(path)

Abstract

The abstract section is particularly useful for possible automatic data retrieval (as in such way is clearly identifiable from the rest of the paper). The output will figure the <h2>Abstract</h2> in the top of the div and at the bottom a div containing the keywords (if defined in the YAML head).

@abstract
Lorem ipsum ....

@/

Table of Contents

To show the table of contents simple use the @toc command:

@toc

# Chapter
Lorem ipsum

## Subsection
Lorem ipsum

Floating elements

Is possible to use floating elements such as figures, listings and tables:

Example:

@figure(ref_id)
![](path)
@caption(your caption)
@/

The code included in the figure is user defined and can be anything not only an image. The ref_id is not obligatory as the caption. The syntax for listings and tables is similar:

@table(id)

@/

@listing(id)

@/

Numbered equation

The numbered equation works as the other floating elements but without any captioning possible:

@equation(id)
x = \sum_{i=1}{N} i
@/

In line and block equation with the classical syntax $inline equation$ and $$block equation$$ are still available but not numbered.

Reference

To refer to a figure, a listing, a table or an equation labeled is enough to write (#id) and it will be replaced by (<a href="#id">number</a>) where number is the number that appear in the caption.

Plots

using the charter syntax in a code block:

```charter
plot:
  x: 1 2 3 4
  y: math:x^2
```

Example

An example of scidwon syntax is available in the examples/ folder.

Some LaTeX and PDF generated from scidown are available in the same as well: article, report

This is a screenshot of the parsing of a simple example using the scidown_article.css style:

The following is the same document using instead the scidown_report.css style:

scidown's Issues

Custom formatting commands

One of the most powerful features of LaTeX in my opinion is the ability to create custom commands and environments.

Although the way Scidown works is fundamentally different, we might be able to reproduce this with CSS.

It would be cool if we could do something like this:

@new_style{red_italic_text}
/* CSS rules here */
color: red;
font-style: italic;
@/

This is normal text.
This text follows the CSS rules of our stylesheet (if there is one.)
asdf
asdf
asdf
asdf

@red_italic_text
This text is in our custom environment.
Our stylesheet rules for these blocks are overwritten by the user-defined styles.
This text is all red and italicized.
@/

In practice, the css code in the new_style block would be added to the document for the html class .red_italic_text. Then all of the html tags inside of the @red_italic_text @/ block would have class=".red_italic_text".

Markdown formats inside a <div> tag don't get rendered

A simple example:

<div dir="rtl">

## Some text in Persian

</div>

This results in the heading not being converted to an <h2> tag, and it is not as expected.

Here you can see a working example from CommonMark Spec.

Add flag to include stylesheet from cli

While stylesheets can be statically included using the yaml header, it would be useful to be able to include stylesheets dynamically using the command-line version of scidown.

We could simply add a --style=/path/to/stylesheet.css option so that the user can specify a stylesheet.

Next release date ?

Hi,

When can we expect a release date ?
New version is so great :)

Thanks

"math" blockquote type not supported

Trying to use Marker (which uses scidown) to write GitLab compatible equations, I ran into a problem. scidown and Marker expect equations to be surrounded by $$, whereas GitLab expects math after a triple backtick

.

Scidown does not render labeled LaTeX equations with MathJax

Scidown is a dependency of Marker.
As the result Marker can't render the following LaTeX equations by MathJax engine:

LaTeX equation (`\begin{equation}...\end{equation}`)

\begin{equation}
h(z) = \sinh(z)
\end{equation}

---

LaTeX equation with `\begin{equation}...(\#eq:label)\end{equation}` RMarkdown + bookdown syntax (see [this chapter](https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#equations)):

\begin{equation}
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation}

---

LaTeX equation with `\begin{equation}...\label{label}\end{equation}` label for [xaringan](https://bookdown.org/yihui/rmarkdown/xaringan.html)

\begin{equation}
  g\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
\label{binom2}
\end{equation}

The ReText editor also uses MathJax, but renders these equations normally:

Please add support for the equation syntax to SciDown.

Add feature to have checkboxes or tasklists as in GitHub flavored Markdown

GitHub markdown supports creation of checkboxes by writing [ ] (space inside square brackets) and selected checkbox by [x] (x inside square brackets)

Just like as follows

- [ ] not selected
- [x] selected

So in case when converted to HTML it should be something like ...

<ul>
<li><input type="checkbox">not selected</li>
<li><input type="checkbox" checked>selected</li>
</ul>

Reference: https://blog.github.com/2014-04-28-task-lists-in-all-markdown-documents/
Reference: fabiocolacio/Marker#218

base_folder parameter should be copied with strdup in hoedown_document_new()

I kept running into a double-free error when using Scidown, because apparently the hoedown_document_new does not copy the entire base_folder string, but instead copies the pointer.

This leads to undefined behaviour, because:

1. If I change the contents of the base_folder string after calling hoedown_document_new (), Scidown will no longer have the correct directory.
2. If Scidown frees or modify the string when I still need it, my code will act in an undefined way.

This is the problematic line:

scidown/src/document.c

Line 3309 in 14a78de

doc->base_folder = base_folder;

I would suggest changing it to doc->base_folder = strdup (base_folder)

Also, I would suggest changing the base_folder parameter to be const char* to prevent the string from being corrupted (or at least throw a warning at compile-time).

Improve support for right-to-left languages

steps can be taken to improve support for right-to-left languages.

As suggested by @ronhasson, adding the attribute dir="auto" to lists can improve the look of right-to-left text in lists.

Escape characters in captions

If I want to put parentheses inside of a caption, the closing ) is interpreted as the end of the caption. I can't seem to escape it using the \ character, as shown in the pictures above.

Is there some other escape character in Scidown?