{Docs = Fixtures = Data = Codeblocks} ∈ markdown
github.com/warpfork
twitter.com/warpfork
slides.com/warpfork
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Seriously, it's... regular markdown.
h1
text
codeblock
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
This is the testmark data hunk body.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
This is a markdown "comment".
This is where we put the data block label, in testmark.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Testmark is just... libraries for parsing this bit.
Let's say I want to regenerate some fixture data!
That should be easy.
(works best when it's simple)
1. Only alter the inside of code blocks.
2. Alter nothing else.
3. Hooray: it won't reformat your markdown. Foolproof. Extension-proof!
In golang, we made a convention of enabling fixture regen by running:
go test ./... -testmark.regen
Makes maintaining large suites of test fixtures easy: make changes; run that; then just review the `git diff` to see the effects.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.
Some testmark libraries have helper functions for walking "dirs", globbing, etc.
Often useful for organizing suites of related tests!
You can name things like filesystems.
[testmark]:# (some/dirs/filename.json)
```json
{"data": "data!"}
```
[testmark]:# (some/dirs/otherfile.wat)
```text
no sweat
```
Libraries can help with this.
(Depends on the library.)
(currently only in golang)
Use a callback if you want control. Or just use exec to the shell!
Auto-regen of output is built-in!
Test scripts easily:
[testmark]:# (using-stdin/input)
```
this is stdin and will be echoed
```
Note the "filenames" in a "dir" together:
[testmark]:# (using-stdin/script)
```
cat - | sed 's/ is/ was/' | sed s/will/should/
```
And this is the assertion:
[testmark]:# (using-stdin/output)
```
this was stdin and should be echoed
```
Kinda goes the opposite direction: you write lots of files; embedmd yeets them into your md files.
I used to use it! Personally, I found it caused me a lot of headaches; I keep wanting to edit the md file, and then stubbing my toe hard.
Okay for fixtures.
(Still not super fun to read.)
((Multiline docs, ow.))
Not great for human-readable docs or website emission (without a lot more tooling).
A neat little format for putting multiple files into one file, popular in golang.
Comparable, in a way.
But I find testmark can produce pretty results,
and encourage me to write good narrative docs.
txtar doesn't.
comment1
txtar
comment2
-- file1 --
File 1 text.
-- foo ---
More file 1 text.
-- file 2 --
File 2 text.
-- empty --
-- file 3 --
File 3 text.
If you want something that encourages you to write a story and real examples at the same time...
Then testmark may be what you're looking for.
Testmark
========
It's regular markdown!
[testmark]:# (the-data-name/goes-here.json)
```json
{"this is": "your data block",
"as big": "as you like"}
```
That codeblock is readable -- and patchable! --
using testmark libraries.