[ examples ]

Next to the writing.

Short write-ups with two graphs each. A refactor, an incident, a tradeoff, a pull request. Copy the Svelte and swap the labels for yours. Each graph has its own page if you want the props.

Refactor

You're moving auth checks out of handlers. Show the request path first, then the work in order, with the current week marked.

[ plan ]

[ AUTH ]
request
handler
session util
request
middleware
handler
[ Flow ]
[ PLAN ]
  1. w1 extract session helper
  2. w2 move checks to middleware
  3. w3 delete the old util
[ Timeline ]
usage 
import { GraphFlow } from 'markgraphy'
import { GraphTimeline } from 'markgraphy'

<GraphFlow
	title="AUTH"
	rows={[
		{
			nodes: [
				{ label: 'request' },
				{ label: 'handler' },
				{ label: 'session util', tone: 'muted' }
			]
		},
		{
			nodes: [
				{ label: 'request' },
				{ label: 'middleware', tone: 'accent' },
				{ label: 'handler' }
			]
		}
	]}
/>

<GraphTimeline
	title="PLAN"
	events={[
		{ date: 'w1', label: 'extract session helper', state: 'done' },
		{ date: 'w2', label: 'move checks to middleware', state: 'now' },
		{ date: 'w3', label: 'delete the old util', state: 'next' }
	]}
/>

Incident

p95 crossed the line, you rolled back a flag, and the postmortem is still open. The strip is the two days people felt it.

[ debug ]

[ INCIDENT ]
  1. 14:02 p95 crossed 800ms
  2. 14:11 rolled back the cache flag
  3. 14:40 write the postmortem
[ Timeline ]
[ API ]

Aug 14 Aug 27

79%

up slow down

79 percent uptime over 14 days, Aug 14 to Aug 27
[ Uptime ]
usage 
import { GraphTimeline } from 'markgraphy'
import { GraphUptime } from 'markgraphy'

<GraphTimeline
	title="INCIDENT"
	events={[
		{ date: '14:02', label: 'p95 crossed 800ms' },
		{ date: '14:11', label: 'rolled back the cache flag', state: 'now' },
		{ date: '14:40', label: 'write the postmortem', state: 'next' }
	]}
/>

<GraphUptime
	title="API"
	from="Aug 14"
	to="Aug 27"
	days={[
		'ok',
		'ok',
		'ok',
		'ok',
		'ok',
		'degraded',
		'ok',
		'ok',
		'down',
		'down',
		'ok',
		'ok',
		'ok',
		'ok'
	]}
/>

Pick one

You're choosing a queue. Checks and dashes first. Bundle size only if that's part of the argument.

[ tradeoff ]

[ QUEUE ]
BullMQSQS
  • in-process ✓–
  • retries ✓✓
  • ops redisaws
  • local ✓–
4 features compared across 2 columns
[ Compare ]
[ INSTALL ]
  1. bullmq 48 kb
  2. ioredis 31 kb
  3. aws sdk 120 kb
[ Rank ]
usage 
import { GraphCompare } from 'markgraphy'
import { GraphRank } from 'markgraphy'

<GraphCompare
	title="QUEUE"
	columns={['BullMQ', 'SQS']}
	accent="BullMQ"
	rows={[
		{ label: 'in-process', values: [true, false] },
		{ label: 'retries', values: [true, true] },
		{ label: 'ops', values: ['redis', 'aws'] },
		{ label: 'local', values: [true, false] }
	]}
/>

<GraphRank
	title="INSTALL"
	items={[
		{ label: 'bullmq', value: 48, display: '48 kb' },
		{ label: 'ioredis', value: 31, display: '31 kb' },
		{ label: 'aws sdk', value: 120, display: '120 kb' }
	]}
/>

Pull request

A review comment with a file list and a coverage slope. The reader shouldn't have to open the diff to get the shape.

[ ship ]

[ FILES ]
  • auth.ts new
  • session.ts moved
  • legacy-auth.ts gone
1 added, 1 removed, 1 unchanged
[ Diff ]
[ COVERAGE ]
main this pr
  • auth 41 88
  • billing 72 74
  • docs 11 40
[ Slope ]
usage 
import { GraphDiff } from 'markgraphy'
import { GraphSlope } from 'markgraphy'

<GraphDiff
	title="FILES"
	palette="duo"
	rows={[
		{ label: 'auth.ts', value: 'new', sign: 'add' },
		{ label: 'session.ts', value: 'moved' },
		{ label: 'legacy-auth.ts', value: 'gone', sign: 'remove' }
	]}
/>

<GraphSlope
	title="COVERAGE"
	fromLabel="main"
	toLabel="this pr"
	items={[
		{ label: 'auth', from: 41, to: 88 },
		{ label: 'billing', from: 72, to: 74 },
		{ label: 'docs', from: 11, to: 40 }
	]}
/>

This week

Monday stand-up. The track is the calendar. The numbers are what's in review, blocked, and already shipped.

[ plan ]

[ THIS WEEK ]
  • rfc
  • patch
  • review
monwedfri
3 tasks
[ Gantt ]
[ BOARD ]

  • 4

    in review

  • 2

    blocked

  • 9

    shipped

[ Stat ]
usage 
import { GraphGantt } from 'markgraphy'
import { GraphStat } from 'markgraphy'

<GraphGantt
	title="THIS WEEK"
	columns={20}
	ticks={['mon', 'wed', 'fri']}
	stage="patch"
	items={[
		{ label: 'rfc', start: 0, end: 0.4, complete: 1 },
		{ label: 'patch', start: 0.35, end: 0.8, complete: 0.55 },
		{ label: 'review', start: 0.7, end: 1, complete: 0 }
	]}
/>

<GraphStat
	title="BOARD"
	items={[
		{ value: '4', label: 'in review' },
		{ value: '2', label: 'blocked' },
		{ value: '9', label: 'shipped', accent: true }
	]}
/>

Migration

A backfill that's still running. The fill is the share. The figure is the row count, with the last points of the job underneath.

[ ship ]

[ ROWS ]

67%

users table

67 percent users table
[ Meter ]
[ MIGRATED ]

1.2M

of 1.8M rows

67%

1.2M of 1.8M rows. 67%
[ KPI ]
usage 
import { GraphMeter } from 'markgraphy'
import { GraphKpi } from 'markgraphy'

<GraphMeter title="ROWS" value={0.67} caption="users table" />

<GraphKpi
	title="MIGRATED"
	value="1.2M"
	label="of 1.8M rows"
	hint="67%"
	data={[2, 3, 3, 5, 8, 9, 11, 12, 14, 16, 18, 21]}
/>

Give this to an agent: Skill. Every graph in one file: /llms.txt.