Docs/Contribute

Contribute to the docs website

Clone the website, run it locally, and add documentation pages through the shared content model.

Clone and start the website#

Install a current Node.js version compatible with the checked-in dependencies and npm. Clone the website repository and install the locked dependency versions. Generate Cloudflare runtime types before starting the development server.

Terminal
git clone https://github.com/junglehornet/oceanlang-website.git
cd oceanlang-website
npm ci
npm run gen
npm run dev

Open the local URL printed by Vite. The website uses SvelteKit, Svelte 5, TypeScript, and the Cloudflare adapter. Local content editing does not require deploying the site.

Find the content and components#

Most documentation edits belong in src/lib/docs.ts. The catch-all docs route looks up a page by slug and renders its sections. The shared layout and index read the same content to build navigation.

Find the content and components reference
PathPurpose
src/lib/docs.tsPages, section content, sidebar groups, and reading order.
src/routes/docs/[...slug]/+page.tsPage lookup, prerender entries, and previous/next pages.
src/routes/docs/[...slug]/+page.svelteShared article renderer and navigation buttons.
src/routes/docs/+layout.svelte, +page.svelteDocumentation sidebar and index.
src/routes/+layout.svelteSite navigation, theme, and document search.
src/lib/components/Code blocks, inline code, prose, and logo components.
src/routes/layout.cssShared styles and responsive layout.

Add a documentation page#

Add a Doc object to the docs array in src/lib/docs.ts. The slug supplies the URL path after /docs/; for example, language/collections becomes /docs/language/collections/. Choose a slug not already used by another page, without a leading or trailing slash, select an existing group, and add a title, description, and sections. Array order controls the previous/next buttons. To introduce a group, also add its name to groups.

Each section needs a unique id within the page, a title, text, code, and note. Use empty strings for an unused code example or note. Optional after text explains an example, table supplies headers and rows, and links supplies labeled URLs. Separate paragraphs with blank lines and wrap inline code in backticks. In text, after, and note, use \n\n in the TypeScript string to separate paragraphs and backticks to mark inline code. Other Markdown features and raw HTML are displayed as text, not rendered. For clickable links, use the section’s links array rather than Markdown link syntax.

TypeScript
// In the docs array in src/lib/docs.ts:
{
  slug: "contribute/example",
  group: "Contribute",
  title: "Example guide",
  description: "Explain what readers will learn.",
  sections: [{
    id: "overview",
    title: "Overview",
    text: "Describe the workflow and use `inline code` for names.",
    code: "",
    note: "",
    links: [{ label: "Source code", href: "/docs/source/" }]
  }]
}

A content entry automatically appears in the sidebar, documentation index, search, prerender entries, and reading sequence. It does not need a dedicated Svelte route. Keep examples grounded in the compiler and library sources and verify executable examples with Ocean.

Check and build#

Run the type checks and production build after editing. The build generates runtime types and prerenders the documentation. The production build turns each documentation page into prerendered output. The preview command starts a local Wrangler server for that output; it does not deploy the site.

Terminal
# Shell
npm run check
npm run build
npm run preview

Review the edited page at desktop and mobile widths, follow its previous/next links, check the sidebar and search, and try any changed code samples. In your contribution, describe the content or behavior changed and report the checks you ran. Submit documentation changes through a pull request rather than running npm run deploy. The repository’s deployment workflow publishes the website automatically after the pull request is merged into main on GitHub.