Commit 5333eb03 authored by Ubbo Veentjer's avatar Ubbo Veentjer
Browse files

include commonmark extensions for heading anchors and parsing yaml header

 closes #27 / related to #44
parent d29f9755
Pipeline #136352 passed with stages
in 8 minutes and 14 seconds
......@@ -27,6 +27,8 @@ dependencies {
implementation 'io.jsonwebtoken:jjwt:0.9.1'
implementation 'com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider'
implementation 'com.atlassian.commonmark:commonmark:0.14.0'
implementation 'com.atlassian.commonmark:commonmark-ext-heading-anchor:0.14.0'
implementation 'com.atlassian.commonmark:commonmark-ext-yaml-front-matter:0.14.0'
implementation 'info.textgrid.middleware.clients:textgrid-clients:3.4.3'
developmentOnly("org.springframework.boot:spring-boot-devtools")
testImplementation('org.springframework.boot:spring-boot-starter-test') {
......
......@@ -39,6 +39,35 @@ Linking between pages is possible, adress them by their relative adress in the `
```markdown
Find more info on the [syntax](/docs/syntax) page.
```
### Linking within pages / Heading anchors
The [Heading anchor](https://github.com/atlassian/commonmark-java#heading-anchor) extension is activated which generates IDs for heading elements. Which could be used as anchors, this means that you can link to them.
An Example:
A Marddown snippet
# Eine Überschrift
## Eine Unterüberschrift
will be rendered as HTML Elements
<h1 id="eine-überschrift">Eine Überschrift</h1>
<h2 id="eine-unterüberschrift">Eine Unterüberschrift</h2>
which means the ID will be lowercase with hyphens (`-`) instead of spaces. So you can link to them in Markdown like
Siehe [Kapitel 1](#eine-überschrift) und [Kapitel 1.1](#eine-unterüberschrift)
Which allwos creation of a TOC for example. You can also reference headings or subheadings on other pages
see the [voyant-example](/docs/voyant#beispiel)
If you are unsure which ID was generated for a heading inspect the element with the developer tool of your web browser. In Firefox for example you can do this with a click on the heading and the context menu entry "Inspect Element"("Element untersuchen"), which will reveal the id:
![inspecting the anchor id](img/inspect-anchor.png)
### Images
......@@ -48,7 +77,12 @@ There is no place for placing own images yet, I will work on it and update this
For parsing Markdwon and rendering HTML the [commonmark-java](https://github.com/atlassian/commonmark-java) library is used. Currently implemented by this library is the [CommonMark Spec 0.29](https://spec.commonmark.org/0.29/). Look at the [CommonMark Dingus](http://spec.commonmark.org/dingus/) for testing and previewing the syntax.
Currently there are no extensions activated, but there are some [available](https://github.com/atlassian/commonmark-java#extensions), if you need one just ask.
Currently there are two extensions activated, there are some [more available](https://github.com/atlassian/commonmark-java#extensions), if you need one just ask.
Active extensions:
* [Heading anchor](https://github.com/atlassian/commonmark-java#heading-anchor)
* [YAML front matter] (https://github.com/atlassian/commonmark-java#yaml-front-matter)
If there is a need for even more extensions or different syntax we may painlessly switch to [flexmark-java](https://github.com/vsch/flexmark-java) for parsing, which is a commonmark-java fork wich supports a lot more different markdown flavours and extensions.
......@@ -3,18 +3,41 @@ package info.textgrid.rep.markdown;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.Arrays;
import java.util.List;
import org.commonmark.Extension;
import org.commonmark.ext.front.matter.YamlFrontMatterExtension;
import org.commonmark.ext.front.matter.YamlFrontMatterVisitor;
import org.commonmark.ext.heading.anchor.HeadingAnchorExtension;
import org.commonmark.node.Node;
import org.commonmark.parser.Parser;
import org.commonmark.renderer.html.HtmlRenderer;
import com.fasterxml.jackson.databind.ObjectMapper;
// TODO: a service should be better to reuse the parser and renderer?
public class MarkdownUtils {
public static String renderHtml(InputStream in) throws IOException {
List<Extension> extensions = Arrays.asList(
HeadingAnchorExtension.create(),
YamlFrontMatterExtension.create()
);
YamlFrontMatterVisitor visitor = new YamlFrontMatterVisitor();
InputStreamReader reader = new InputStreamReader(in);
Parser parser = Parser.builder().build();
Parser parser = Parser.builder()
.extensions(extensions).build();
Node document = parser.parseReader(reader);
HtmlRenderer renderer = HtmlRenderer.builder().build();
document.accept(visitor);
// TODO: remove - some test output for yaml headers
ObjectMapper objectMapper = new ObjectMapper();
System.out.println(objectMapper.writeValueAsString(visitor.getData()));
HtmlRenderer renderer = HtmlRenderer.builder()
.extensions(extensions).build();
return renderer.render(document);
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment