Pikchr – PIC-like markup language for diagrams in technical documentation(pikchr.org)
pikchr.org
Pikchr – PIC-like markup language for diagrams in technical documentation
https://pikchr.org/home/doc/trunk/homepage.md
12 comments
Pikchr is awesome! I'll just mention that the Markdown-based note-taking app I'm working on as far as I know is the only app on the planet that can syntax-highlight Pikchr code: https://github.com/notable/notable-insiders/releases/tag/v1....
Pikchr is really great. The syntax looks strange at first, but the learning curve is actually low. Within 5 minutes of looking at the pikchr source of some SQLite diagrams, you'll get it. I use it to produce railroad syntax diagrams in the same style as the ones in the SQLite docs. I don't use the Markdown integration; I just generate SVGs using PikchrShow[0] and treat them as images in my HTML-based docs.
[0] https://pikchr.org/home/pikchrshow
[0] https://pikchr.org/home/pikchrshow
I'm the type of guy that would store the Pikchrs in the version control system alongside the HTML, then write a Makefile to regenerate the SVGs referenced from the HTML every time the Pikchrs change.
But at that point, you might as well just use Fossil as a CMS. :)
https://fossil-scm.org/home/doc/trunk/www/wikitheory.wiki
But at that point, you might as well just use Fossil as a CMS. :)
https://fossil-scm.org/home/doc/trunk/www/wikitheory.wiki
I have used both Pikchr and several of the Mediawiki extensions for diagrams (the most recently-maintained of which is https://www.mediawiki.org/wiki/Extension:Flex_Diagrams )
Here is my earliest Pikchr effort: https://lumosql.org/src/not-forking (click to see source.)
Pikchr diagrams are crisp and precise with zero configuration. Mermaid diagrams are difficult to make render as nicely as the screenshots show (https://mermaid-js.github.io ) and easier to confuse with ambiguous syntax.
With the addition of 5 lines Lua, Pandoc now handles Pikchr in Markdown documents: https://groups.google.com/g/pandoc-discuss/c/zZSspnHHsg0/m/m...
Here is my earliest Pikchr effort: https://lumosql.org/src/not-forking (click to see source.)
Pikchr diagrams are crisp and precise with zero configuration. Mermaid diagrams are difficult to make render as nicely as the screenshots show (https://mermaid-js.github.io ) and easier to confuse with ambiguous syntax.
With the addition of 5 lines Lua, Pandoc now handles Pikchr in Markdown documents: https://groups.google.com/g/pandoc-discuss/c/zZSspnHHsg0/m/m...
> Pikchr is designed to be embedded in fenced code blocks of Markdown
Odd choice, usually that's how you'd show the (possibly syntax-highlighted) code as-is, not execute/render it in situ.
E.g. what if I want a document that says 'this pikchr code generates this'? I'd expect to write something like:
Odd choice, usually that's how you'd show the (possibly syntax-highlighted) code as-is, not execute/render it in situ.
E.g. what if I want a document that says 'this pikchr code generates this'? I'd expect to write something like:
```pikchr
arrow 200% "whatever"
```
renders:
$pikchr
arrow 200% "whatever"
$
If you leave off the "pikchr" tag or use something else like "PikchrSource", then the renderer doesn't trigger.
If you want to see it both ways, Fossil renders the diagrams with an Alt or Ctrl-click handler attached (depending on platform) that toggles between the SVG and the fixed-width source code view.
And if you don't like the modifier key, you can tag a diagram "pikchr toggle" to make it toggle with a simple left-click.
If you want to see it both ways, Fossil renders the diagrams with an Alt or Ctrl-click handler attached (depending on platform) that toggles between the SVG and the fixed-width source code view.
And if you don't like the modifier key, you can tag a diagram "pikchr toggle" to make it toggle with a simple left-click.
Sure, but usually specifying "pikchr" (or whatever) means syntax-highlight as appropriate to that language; not execute as that language.
That's maybe the most interesting idea out of the whole setup!
You could reasonably put options on the fenced-code-block header line:
You could reasonably put options on the fenced-code-block header line:
```pikchr --source
...
```
```pikchr --caption # caption rendered figure with source
...
```
I wasn't aware of this & looks like worth learning. I was looking ahead to learn Penrose (https://penrose.ink/) for making diagrams in my notes.
contrary to pikchr documentation, troff is not obsolete
No technology popular enough to attract an audience ever goes away. However, would you care to speculate on how many troff documents were written in 2021 versus Markdown docs?
It's a great little diagram language that's quite capable, and I think of it like a modern web upgrade to Brian Kernighan's PIC.