Zaephyrus Usage

There are basically two ways to use Zaephyrus: as an image, and as text. Requesting an image from the API will generate the SVG on the server. Zaephyrus can be run as a client-side script to parse the text and replace it with SVG generate the SVG in the browser.

The biggest difference between the two options is how much control will be available in the styling of the SVG elements; rendering the objects client-side will allow for more options when styling.

Zaephyrus Grammar

There are only four parts to the grammar: branch (b), commit (c), merge (m), and tag (t). This isn't much but enables creating rather complex diagrams and covers most use cases.

Zaephyrus Playground

The /graphs endpoint enables the creation of adhoc Git history graphs as SVG images; for embedding into Markdown documents on GitHub for instance. This "playground" helps with learning the simplified Git syntax to build image URLs.

Zaephyrus Text

The client-side script will look for pre tags with the language attribute set to "zaephyrus" (as seen below) and will replace it with the SVG graph.

HTML PRE Tag Include


<pre lang="zaephyrus">
  branch main
  commit "initial commit"
  tag v1.0.0
  branch feature-branch
  commit "make it work"
  commit "make it better"
  branch main
  merge feature-branch
  tag v1.1.0
</pre>

<!-- ... -->

<script defer src="https://zaephyr.us/graphs/zaephyrus.js"></script>
  
    branch main
    commit "initial commit"
    tag v1.0.0
    branch feature-branch
    commit "make it work"
    commit "make it better"
    branch main
    merge feature-branch
    tag v1.1.0

Markdown Fenced Code Block

A fenced code block using zaephyrus would look like this (below), and would get rendered into looking similar to the HTML PRE tag include (above).


``` zaephyrus
  branch main
  commit "initial commit"
  tag v1.0.0
  branch feature-branch
  commit "make it work"
  commit "make it better"
  branch main
  merge feature-branch
  tag v1.1.0
```
  
    branch main
    commit "initial commit"
    tag v1.0.0
    branch feature-branch
    commit "make it work"
    commit "make it better"
    branch main
    merge feature-branch
    tag v1.1.0

Zaephyrus Image

The images can also be created on "the server" instead of relying on client-side processing. This can be accomplished with img tags in html or image references in Markdown.

HTML IMG Tag


<img src="https://zaephyr.us/graphs?b=main&c=initial%20commit&b=feature-branch&c=make%20it%20work&c=make%20it%20better&b=main&m=feature-branch" />
git history graph

Markdown Image Reference


![git history graph](https://zaephyr.us/graphs?b=main&c=initial%20commit&b=feature-branch&c=make%20it%20work&c=make%20it%20better&b=main&m=feature-branch)
git history graph