Code Examples¶

This page demonstrates code blocks with syntax highlighting, line numbers, and copy-to-clipboard functionality in Java, YAML, and Bash. It also includes code tabs and Mermaid diagrams.

Java Example¶

The following Java snippet shows a simple service class:

package com.example.service;

import java.util.Optional;

/**
 * Example service class for the Zensical POC.
 */
public class HelloService {

    public Optional<String> greet(String name) {
        if (name == null || name.isBlank()) {
            return Optional.empty();
        }
        return Optional.of("Hello, " + name + "!");
    }

    public static void main(String[] args) {
        var service = new HelloService();
        service.greet("Zensical").ifPresent(System.out::println);
    }
}

YAML Example¶

Configuration for a CI pipeline:

name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build docs
        run: zensical build
      - name: Deploy
        uses: actions/upload-pages-artifact@v3
        with:
          path: site/

Bash Example¶

Build and serve locally:

#!/bin/bash
set -e

# Build documentation
zensical build

# Optional: serve locally
zensical serve

Language tabs¶

Use tabs to present equivalent snippets in multiple languages while saving vertical space. Zensical supports this via the content tabs extension.

Same workflow in different formats:

npm install
npm run start

# Build the static site
npm run build

scripts:
  start: docusaurus start
  build: docusaurus build

{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build"
  }
}

Code tabs (shells)¶

Compare the same command across shells:

zensical serve

zensical serve

zensical serve

Code Annotations¶

Zensical supports code annotations — clickable markers that reveal explanations inline. See the documentation.

def factorial(n):
    if n <= 1:
        return 1  # (1)!
    return n * factorial(n - 1)  # (2)!

1. Base case: factorial of 0 or 1 is 1.
2. Recursive case: multiply n by the factorial of n - 1.

Mermaid Diagrams¶

Sequence Diagram¶

sequenceDiagram
    participant User
    participant Zensical
    participant GitHub

    User->>Zensical: zensical build
    Zensical->>Zensical: Render Markdown
    Zensical->>User: site/ output
    User->>GitHub: Push to main
    GitHub->>GitHub: Run deploy workflow
    GitHub->>User: Live at GitHub Pages

Class Diagram¶

classDiagram
    class Zensical {
        +build()
        +serve()
    }
    class Theme {
        +palette
        +search
        +features
    }
    Zensical --> Theme : uses

Flowchart¶

Doc build pipeline:

flowchart LR
    subgraph Source
        MD[Markdown Files]
        Config[zensical.toml]
    end

    subgraph Build
        Zensical[Zensical Build]
    end

    subgraph Output
        HTML[Static HTML Site]
        Site[GitHub Pages]
    end

    MD --> Zensical
    Config --> Zensical
    Zensical --> HTML
    HTML --> Site

Tables and Admonitions¶

Feature Support¶