Skip to main content

ODS Doc

A TypeScript library for generating comprehensive Markdown documentation from Open Domain Specification (ODS) workspaces. This package automatically creates structured documentation with embedded diagrams, relationship tables, and navigation for domain-driven design projects.

👀 Check out the ODS Example Workspace documentation and hosted Docsify site: https://eshop.open-ds.io https://github.com/Open-Domain-Specification/open-domain-specification/tree/main/packages/ods-example-ws

Features​

  • Hierarchical Documentation: Generate complete documentation trees from workspace to aggregate level
  • Embedded Visualizations: Automatically include context maps, consumable maps, and relation maps as SVG diagrams
  • Relationship Tables: Generate tables showing consumption patterns and relationships between components
  • Navigation Structure: Create sidebar navigation with proper hierarchy and cross-linking
  • Breadcrumb Navigation: Optional breadcrumb trails for easy navigation
  • Multiple Component Types: Support for workspaces, domains, subdomains, bounded contexts, services, and aggregates

Installation​

npm install @open-domain-specification/doc

Usage​

At its core the @open-domain-specification/doc package provides a single function toDoc that converts the workspace to a Dictionary of Markdown files.

The function accepts an ODSWorkspace instance and returns a dictionary where keys are file paths and values are Markdown content.

See the Example Workspace for a complete example of how to use the toDoc function and generate documentation.

import { Workspace } from "@open-domain-specification/core";
import { toDoc } from "@open-domain-specification/doc";
import { describe, expect, it } from "vitest";

const ws = new Workspace("eCommerce", {
	odsVersion: "1.0.0",
	description: "DDD workspace for an eCommerce platform example",
	version: "0.1.0",
	homepage: "https://example.com",
	primaryColor: "#0ea5e9",
	logoUrl: "https://example.com/logo.svg",
});

const wsMd = `

# eCommerce
DDD workspace for an eCommerce platform example

![contextmap](./contextmap.svg)

## Domains
> No domains.

## Relationships
	

`;

const contextMap = `\
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?xml-stylesheet href="data:text/css,.graph%20text%20%7B%0A%09font-family%3A%20sans-serif%3B%0A%09stroke%3A%20white%3B%0A%09paint-order%3A%20stroke%3B%0A%09stroke-width%3A%203%3B%0A%09stroke-linecap%3A%20square%3B%0A%7D%0A%0A.namespace%20polygon%20%7B%0A%09fill-opacity%3A%200.2%3B%0A%09stroke%3A%20none%3B%0A%7D%0A" type="text/css"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 13.1.2 (0)
 -->
<!-- Pages: 1 -->
<svg width="8pt" height="8pt"
 viewBox="0.00 0.00 8.00 8.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 4)">
<polygon fill="white" stroke="none" points="-4,4 -4,-4 4,-4 4,4 -4,4"/>
</g>
</svg>
`;

describe("Generate example documentation", () => {
	it("should generate docs", async () => {
		expect(await toDoc(ws)).toEqual({
			"_sidebar.md": "* [eCommerce](/e_commerce/index.md)",
			"e_commerce/contextmap.svg": contextMap,
			"e_commerce/index.md": wsMd,
		});
	});
});

The generated documentation includes a sidebar navigation structure that reflects the hierarchy of the ODS workspace. Each component type (workspace, domain, subdomain, bounded context, service, aggregate) has its own section in the sidebar.

This is crafted for ease of use with Docsify or similar documentation generators that support hierarchical navigation, however you can also create your own custom navigation structure based on the generated Markdown files.