README.md
1Scidown
2=======
3
4`Scidown` is a fork of [Hoedown](https://github.com/hoedown/hoedown),
5a 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.
6
7For more information on the syntax and example look at the **[wiki](https://github.com/Mandarancio/scidown/wiki)**.
8
9More about the motivation and the planning of the project in the **[manifesto](MANIFESTO.md)**.
10
11Features
12--------
13
14* **Integrated plot** using [charter](https://github.com/mandarancio/charter) and experimental support to `gnuplot`
15* **Figures, Tables and Listings with caption**
16* **YAML header** specify title, authors, css style, keywords and more
17* **Abstract** syntax for defining abstracts
18* **Include external files** include external files to build complex documents
19
20Markdown Differences
21--------------------
22A 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:
23
24 * `# title` becomes `<h2>title</h2>` instead of `<h1>`
25 * `## subtitle` becomes `<h3>subtitle</h3>` instead of `<h2>`
26 * well I suppose you get it all the headers are shifted of one
27
28This is due the addition of the title information in form of `YAML` head as explained in the following section.
29
30Compile and Run
31---------------
32To compile the project simply do the following:
33```bash
34git submodule update --init --recursive
35mkdir build
36cd build
37meson ..
38ninja
39```
40
41To install it simply run ```sudo ninja install``` inside the build folder.
42The executable `scidown` will be now available in the build folder, to use it simply:
43
44```bash
45scidown input.md
46# print out the html or to save it
47scidown input.md > output.html
48```
49
50Special Syntax
51--------------
52
53### YAML Head
54
55Is possible to add information and configuration in form of a `YAML` header:
56
57```markdown
58---
59title: your title
60author: author 1
61author: author 2
62affiliation: affiliation
63style: css file
64keywords: list of keywords
65numbering: true/false (number the chapters, sections and subsections)
66---
67
68Rest of your markdown file
69```
70
71the `title`, `author` and `keywords` will be used both as metadata of the html and displayed in the output.
72
73### External Files
74
75Is possible to include external files to make easier work with big documents:
76
77```markdown
78@include(path)
79```
80As bibliography only:
81
82```markdown
83@bib(path)
84```
85
86### Abstract
87
88The abstract section is particularly useful for possible automatic data retrieval (as in such way is clearly identifiable from the rest of the paper).
89The 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).
90
91```markdown
92@abstract
93Lorem ipsum ....
94
95@/
96```
97
98### Table of Contents
99
100To show the table of contents simple use the `@toc` command:
101
102```markdown
103@toc
104
105# Chapter
106Lorem ipsum
107
108## Subsection
109Lorem ipsum
110```
111
112### Floating elements
113
114Is possible to use floating elements such as figures, listings and tables:
115
116Example:
117```markdown
118@figure(ref_id)
119
120@caption(your caption)
121@/
122```
123The 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`.
124The syntax for listings and tables is similar:
125
126```markdown
127@table(id)
128
129@/
130
131@listing(id)
132
133@/
134```
135
136### Numbered equation
137
138The numbered equation works as the other floating elements but without any captioning possible:
139
140```markdown
141@equation(id)
142x = \sum_{i=1}{N} i
143@/
144```
145
146In line and block equation with the classical syntax `$inline equation$` and `$$block equation$$` are still available but not numbered.
147
148### Reference
149To 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.
150
151### Plots
152
153using the `charter` syntax in a code block:
154
155~~~markdown
156```charter
157plot:
158 x: 1 2 3 4
159 y: math:x^2
160```
161~~~
162
163
164
165Example
166--------
167An example of `scidwon` syntax is available in the ```examples/``` folder.
168
169Some `LaTeX` and `PDF` generated from `scidown` are available in the same as well: [article](https://github.com/Mandarancio/scidown/raw/master/examples/example_article.pdf), [report](https://github.com/Mandarancio/scidown/raw/master/examples/example_report.pdf)
170
171This is a screenshot of the parsing of a simple example using the `scidown_article.css` style:
172
173
174
175The following is the same document using instead the `scidown_report.css` style:
176
177
