Add README

stefanfritsch · Oct 13, 2022 · 642395e · 642395e
1 parent affa836
commit 642395e
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,2 +1,44 @@
-# goldmark-fences
-Fenced divs for the Goldmark go markdown renderer
+# Goldmark-Fences
+
+## Overview
+
+[Goldmark](github.com/yuin/goldmark) is a fast markdown renderer for Go. Fences are a markdown extension that allows you to wrap parts of a markdown in a `<div>` or other html-tag with custom classes, ids or other html attributes.
+
+Fences are also called "fenced divs" or "fenced containers." I will use fences because it's the shortest of the available options.
+
+### An Example
+
+```markdown
+:::{.blue}
+## Life Inside Fences
+
+We are now inside a div with the css-class "blue". This can be used to style this block
+
+:::{#insideme .red data="important"}
+fences can be nested and given ids as well as classes
+:::
+:::
+```
+
+Now add the css to your stylesheet:
+
+```css
+.blue { background-color: steelblue; padding: 5px; }
+#insideme { color: yellow; }
+.red { background-color: red; }
+```
+
+And the fenced part will look like this (this is an image as github doesn't allow custom css in READMEs):
+
+![](assets/Screenshot%202022-10-14%20001453.png)
+
+## Possible Use Cases
+
+You can use fences to e.g.
+
+* style your output
+* wrap semantic units into blocks - e.g. put your toc into one div - which allows you to...
+* move parts outside the normal layout - e.g. create a floating toc on the left
+* fulfill the requirements of third party libs regarding attributes like `data=` etc.
+* use it for other extensions -- e.g. to wrap all sections in divs for a semantic output structure
+* create random html creations
diff --git a/assets/Screenshot 2022-10-14 001453.png b/assets/Screenshot 2022-10-14 001453.png
diff --git a/extend.go b/extend.go
@@ -10,7 +10,7 @@ import (
 // Extender allows you to use fenced divs / fenced containers / fences in markdown
 //
 // Fences are a way to wrap other elements in divs and giving those divs
-// attributes using the same syntax as with headings.
+// attributes such as ids or css classes using the same syntax as with headings.
 //
 // :::{#big-div .add-border}
 // this is some text