Zykov Official User Guide

1. Introduction

1.1 What is a graph?

A graph is a structure made of nodes and edges. Nodes represent things; edges represent relations between those things.

A * B

In Zykov, this expression creates two nodes and connects them.

1.2 What is a semantic page?

A semantic page is a web page where information is organized as a navigable system of meanings. Instead of only reading from top to bottom, the reader can explore rooms, topics, nodes, relationships, and text fragments.

• A museum archive can connect works, artists, periods, and techniques.
• A research notebook can connect definitions, lemmas, diagrams, and examples.
• A newsroom can connect sources, events, timelines, and interpretations.

1.3 Why Zykov?

Zykov makes graph topology readable and writable. It treats relationships not as hidden data structures, but as part of the reading experience.

2. Zykov 101

2.1 Installation

npm install -g .
zygrafi --help

2.2 Your first semantic page

Title = "Hello Zykov"
Background = "#dfe7e1"

all = {
  Title:"This is your first semantic page",
  Text:"Here you can test your semantic page."
}

Room = hello * zykov

entry hello = {
  Title:"Hello",
  Text:"This is a semantic publication node."
}

entry zykov = {
  Title:"Zykov",
  Text:"Zykov transforms graph expressions into navigable semantic spaces."
}

gallery = {
  Room -> "Main Room"
}

zygrafi build hello.zyk

2.3 Topics and filters

Categories = {
  idea -> "#4db6ac",
  note -> "#ce93d8"
}

Room = (write + draw + build) :: idea
+ path([hello,zykov,notelab]) :: note

2.4 Adding text

entry write = {
  Title:"Write",
  Text:"Use Zykov expressions to describe relations as graph algebra."
}

2.5 Color

Background = "#dfe7e1"

NodesColor = {
  entries -> "#34495e",
  general -> "#5d6d7e"
}

EdgesColor = "#7ac9a2"

2.6 Rooms

roomData "Main Room" = {
  Title: "Zygrafi NoteLab",
  Text: "A notebook-like laboratory for Zykov scripts."
}

2.7 Your first gallery

gallery = {
  Room -> "Main Room"
}

3. Tools for Designers

zygrafi studio
zygrafi studio myproject.zyk
zygrafi diagnostic myproject.zyk
zygrafi colorchart myproject.zyk

4. Graph Model

The central structure of Zykov is a graph with vertices, edges, and optional metadata.

Graph = (V, E, nodeMeta)

The language evaluates graph expressions into this structure. The renderer then turns the graph and its metadata into a navigable interface.

5. Core Operators

(A + B) :: Cat = A :: Cat + B :: Cat
A * (B + C) = A*B + A*C

6. Editorial Layer

6.1 all

all = {
  Title: "Untitled Notebook",
  Text: "A first semantic note in Zygrafi NoteLab."
}

6.2 topic

topic Note = {
  Title: "Note",
  Text: "General note nodes."
}

6.3 entry

entry Start = {
  Title: "Start",
  Text: "Write your first note here.",
  Image: "",
  Hypertext: {
    Note -> "This text appears when the topic filter is Note."
  }
}

6.4 room and roomData

roomData "Main Room" = {
  Title: "Main Room",
  Text: "Introductory room text."
}

7. Lists and Generators

7.1 forList

L = forList(1, 5, V)
// [V1, V2, V3, V4, V5]

7.2 listFrom

Chapters = listFrom(ch, [71,5,81,74,6,7])

7.3 seqList

seqList(V, i, 1, 3, "3*i-(3-2)+(j-1)")

7.4 repeat, flatten, concat, elim

nums = forList(1, 4, V)
more = repeat(2, nums)
flat = flatten([nums, [Start]])
joined = concat(nums, [Start])
less = elim(nums, [V2, V4])

8. Graph Constructors

path([A,B,C,D])

cycle([A,B,C,D])

star(Center,[A,B,C])

agg([G1,G2])
link([A,B,C])

9. Graph Inspection

• V(G): list of vertex names.
• Vlist(G): list of singleton graph vertices.
• Vcat(G, [C1,C2]): vertices by category.
• Ventry(G): vertices without explicit category.
• at(L, i): 1-indexed list access.
• len(L): list length.

verts = V(G)
singletons = Vlist(G)
notes = Vcat(G, [Note])
first = at(singletons, 1)
total = len(verts)

10. Style System

10.1 Global style variables

Background = "#f8fafc"

Categories = {
  Note -> "#64748b",
  Runtime -> "#ff006e"
}

NodesColor = {
  entries -> "#002FA7",
  general -> "#111827"
}

EdgesColor = {
  general -> "#cbd5e1"
}

10.2 roomDesign

roomDesign WhyRoom = {
  Background: BackgroundWhy,
  Categories: CategoriesWhy,
  Nodes: NodesWhy,
  Edges: EdgesWhy
}

10.3 styleGraph, styleRoom, styleChart

Styled = styleGraph(
  G,
  "#f8fafc",
  { Note -> "#64748b" },
  { general -> "#111827" },
  { general -> "#cbd5e1" }
)

StyledRoom = styleRoom(WhyRoom)
Chart = styleChart(StyledRoom)
Chart2 = styleChartFrom(WhyRoom)

10.4 ColorChart as design documentation

zygrafi colorchart myproject.zyk

ColorChart produces a visual atlas of global and room-specific palettes.

11. Guide for Mathematicians

11.1 Your first field notebook

Title = "Graph Field Notebook"

G = A * (B + C) + path([D,E,F])

entry A = {
  Title:"A",
  Text:"A distinguished vertex in the working graph."
}

gallery = {
  G -> "Working Graph"
}

11.2 Documenting equations

entry Equation = {
  Title:"Graph equation",
  Text:"This room documents a graph built from join and overlay operations."
}

11.3 Equation generalization

triangle(a,b,c) = a*b + b*c + a*c
Room = triangle(A,B,C)

11.4 N-ary trees

naryTreeNode(X,i,n) = valNode(V,"i") * agg(seqList(X,i,1,n,"n*i-(n-2)+(j-1)"))
nary(Alias,layer,n) = agg(mapListWhere(1,layer,naryTreeNode,Alias,n))
G4 = nary(V,6,3)

11.5 Graph induction

Verts = Vlist(G)
U1 = elim(Verts, [at(Verts,1)])
H = G @ U1

12–17. Advanced Topics

12. Dictionaries

Colors = {
  Note -> "#475569",
  general -> "#111827"
}

c = get(Colors, "Note", "#999999")

13. Search

Result = search(G, {
  Note -> true,
  Start -> true
})

14. Pipe composition

Chart = WhyRoom |> styleRoom |> styleChart
Rayuela = listFrom(ch,[71,5,81,74,6,7]) |> path

15. Guards

f(x) = x == 0 -> A
| else -> B

16. Where clauses

f(x) = pattern(i) where pattern(i) = ...

17. Reusable graph patterns

line(a,b,c,d) = path([a,b,c,d])
hub(c,a,b,d) = star(c,[a,b,d])

18. Examples

18.1 Minimal note

all = {
  Title: "Mini note",
  Text: "A minimal graph."
}

topic Note = {
  Title: "Main topic",
  Text: "Basic nodes."
}

entry A = { Title: "A", Text: "First node." }
entry B = { Title: "B", Text: "Second node." }

G = (A + B) :: Note

gallery = {
  G -> "Mini note"
}

18.2 Path graph

L = forList(1,5,V)
G = path(L)

18.3 Cycle graph

L = forList(1,5,V)
G = cycle(L)

18.4 Star graph

Leaves = forList(1,4,V)
G = star(Center, Leaves)

18.5 Semantic notebook

Title = "Notebook"
Background = "#dfe7e1"

Categories = { idea -> "#4db6ac", note -> "#ce93d8" }

Room = idea :: idea * (write + draw + build + publish)
+ path([hello,zykov,notelab]) :: note

gallery = { Room -> "Main Room" }

18.6 Multi-room gallery

gallery = {
  Computers -> "Computers 1960-1990",
  Anthropology -> "20th Century Anthropology",
  Sneakers -> "Sneaker History"
}

18.7 Style chart

Chart = WhyRoom |> styleChartFrom

18.8 Typical workflow

zygrafi studio myproject.zyk
zygrafi diagnostic myproject.zyk
zygrafi colorchart myproject.zyk
zygrafi build myproject.zyk