Status Active Development License: MIT

Note: BJJGraph is under active development. Content is being expanded daily. Contributions welcome!

Brazilian Jiu-Jitsu knowledge graph and state machine as a static site.

Live Site: bjjgraph.org

• 95+ Positions - BJJ positions as state machine nodes
• 71+ Transitions - Techniques as probabilistic edges between states
• 49+ Submissions - Terminal states and finishing techniques
• Expert Systems - Systematic approaches from Danaher, Gordon Ryan, Eddie Bravo
• Interactive Graph - Visual exploration of position relationships

cd source
npm install # Install dependencies (Node 20+)
npx quartz build --serve # Development server at localhost:8080

Before making changes, run these commands:

# 1. Validate JSON source files
python3 scripts/validate_json.py
# 2. Regenerate markdown from JSON
python3 scripts/json_to_md.py
# 3. Build the site
cd source && npx quartz build
# 4. Run type checking
cd source && npm run check

BJJGraph uses a JSON-first content system:

1. Edit JSON source files in source/content/
2. Validate with python3 scripts/validate_json.py
3. Regenerate markdown with python3 scripts/json_to_md.py
4. Test build with npx quartz build --serve

Never edit .md files in source/content/ directly - they are generated from JSON.

Built on Quartz 4.0 with:

• Interactive graph visualization (D3.js)
• Full-text search (Flexsearch)
• PostHog analytics
• Mobile-responsive design
• Schema markup for SEO (HowTo, FAQ)

bjjgraph/
├── source/
│ ├── content/ # Content files (JSON source + generated MD)
│ │ ├── Positions/ # 95+ positions
│ │ ├── Transitions/ # 71+ transitions
│ │ ├── Submissions/ # 49+ submissions
│ │ ├── Systems/ # Expert systems
│ │ └── Principles/ # Fundamental principles
│ ├── templates/ # Jinja2 templates for MD generation
│ └── quartz/ # Static site generator
├── scripts/ # Validation and automation
├── docs/ # Project documentation
└── tests/ # Test artifacts

BJJGraph is building the most comprehensive, systematic breakdown of grappling ever assembled. Our mission is to democratize high-level BJJ knowledge so anyone with the interest can truly study the game.

We're looking for partners who share this vision—BJJ apps, gear companies, academies, and training platforms who want to help advance the sport and make world-class instruction accessible to all.

Contact: Diogo Seca on LinkedIn

• PostHog: https://us.posthog.com/project/236155
• SEO: Schema markup on all content pages

MIT License - see LICENSE

• Site: https://bjjgraph.org
• Repository: https://github.com/diogoseca/bjjgraph
• Quartz Docs: https://quartz.jzhao.xyz/