docs: comprehensive documentation site improvements

- Remove orphaned template files (guides/example.md, reference/example.md)
- Add missing production pages: publishing.mdx, performance.mdx
- Add comprehensive example pages: calculator.mdx, http-service.mdx, multi-language.mdx
- Update sidebar configuration with all new pages
- Fix Starlark syntax highlighting using Python grammar alias
- Resolve all broken internal links and references

All documentation pages now exist and build successfully with proper syntax highlighting.

Author: avrabe

MODULE.bazel.lock

@@ -25,11 +25,24 @@ def _cpp_component_impl(ctx):
     headers = ctx.files.hdrs
     wit_file = ctx.file.wit
 
-    # Collect dependency headers
+    # Collect dependency headers and libraries using CcInfo provider
     dep_headers = []
     dep_libraries = []
+    dep_includes = []
+    
     for dep in ctx.attr.deps:
-        if DefaultInfo in dep:
+        if CcInfo in dep:
+            # Use proper CcInfo provider for header and library information
+            cc_info = dep[CcInfo]
+            dep_headers.extend(cc_info.compilation_context.headers.to_list())
+            dep_includes.extend(cc_info.compilation_context.includes.to_list())
+            # Extract static libraries from linking context
+            for linker_input in cc_info.linking_context.linker_inputs.to_list():
+                for library in linker_input.libraries:
+                    if library.static_library:
+                        dep_libraries.append(library.static_library)
+        elif DefaultInfo in dep:
+            # Fallback for non-CcInfo dependencies (e.g., legacy rules)
             for file in dep[DefaultInfo].files.to_list():
                 if file.extension in ["h", "hpp", "hh", "hxx"]:
                     dep_headers.append(file)
@@ -74,7 +87,17 @@ def _cpp_component_impl(ctx):
 
     # Basic compiler flags for Preview2
     compile_args.add("--target=wasm32-wasip2")
-    compile_args.add("--sysroot=" + sysroot)
+    # Compute sysroot path from sysroot_files for external repository compatibility
+    if sysroot_files and sysroot_files.files:
+        # Use the directory containing the sysroot files as the sysroot path
+        sysroot_file = sysroot_files.files.to_list()[0]
+        # Extract the repository-relative sysroot path
+        sysroot_path = sysroot_file.path.split("/sysroot/")[0] + "/sysroot"
+    else:
+        # Fallback to configured path
+        sysroot_path = sysroot
+    
+    compile_args.add("--sysroot=" + sysroot_path)
 
     # Component model definitions
     compile_args.add("-D_WASI_EMULATED_PROCESS_CLOCKS")
@@ -112,16 +135,21 @@ def _cpp_component_impl(ctx):
 
     # Add C++ standard library paths for wasm32-wasip2 target
     if ctx.attr.language == "cpp":
-        compile_args.add("-I" + sysroot + "/include/wasm32-wasip2/c++/v1")
-        compile_args.add("-I" + sysroot + "/include/c++/v1")
+        compile_args.add("-I" + sysroot_path + "/include/wasm32-wasip2/c++/v1")
+        compile_args.add("-I" + sysroot_path + "/include/c++/v1")
 
     for include in ctx.attr.includes:
         compile_args.add("-I" + include)
 
-    # Add dependency header directories
+    # Add dependency include directories from CcInfo
+    for include_dir in dep_includes:
+        if include_dir not in [work_dir.path] + ctx.attr.includes:
+            compile_args.add("-I" + include_dir)
+    
+    # Add dependency header directories (fallback for non-CcInfo deps)
     for dep_hdr in dep_headers:
         include_dir = dep_hdr.dirname
-        if include_dir not in [work_dir.path] + ctx.attr.includes:
+        if include_dir not in [work_dir.path] + ctx.attr.includes + dep_includes:
             compile_args.add("-I" + include_dir)
 
     # Defines
@@ -400,7 +428,9 @@ def _cc_component_library_impl(ctx):
         # Compile arguments
         compile_args = ctx.actions.args()
         compile_args.add("--target=wasm32-wasip2")
-        compile_args.add("--sysroot=" + sysroot)
+        # Resolve sysroot path dynamically for external repository compatibility
+        sysroot_dir = sysroot_files.files.to_list()[0].dirname if sysroot_files.files else sysroot
+        compile_args.add("--sysroot=" + sysroot_dir)
         compile_args.add("-c")  # Compile only, don't link
 
         # Component model definitions
@@ -480,8 +510,33 @@ def _cc_component_library_impl(ctx):
         progress_message = "Creating component library %s" % ctx.label,
     )
 
+    # Collect transitive headers and libraries from dependencies
+    transitive_headers = []
+    transitive_libraries = []
+    transitive_includes = []
+    
+    for dep in ctx.attr.deps:
+        if CcInfo in dep:
+            cc_info = dep[CcInfo]
+            transitive_headers.append(cc_info.compilation_context.headers)
+            transitive_includes.extend(cc_info.compilation_context.includes.to_list())
+            transitive_libraries.append(cc_info.linking_context.linker_inputs)
+
+    # Create compilation context with current headers and transitive headers
+    compilation_context = cc_common.create_compilation_context(
+        headers = depset(ctx.files.hdrs, transitive = transitive_headers),
+        includes = depset([h.dirname for h in ctx.files.hdrs] + ctx.attr.includes, transitive = [depset(transitive_includes)]),
+    )
+    
+    # Create CcInfo provider with compilation context only
+    # Note: We don't create linking context since we're using custom WASM toolchain
+    cc_info = CcInfo(
+        compilation_context = compilation_context,
+    )
+
     return [
         DefaultInfo(files = depset([library] + ctx.files.hdrs)),
+        cc_info,
         OutputGroupInfo(
             library = depset([library]),
             objects = depset(object_files),

cpp/defs.bzl

@@ -23,7 +23,16 @@ export default defineConfig({
 			expressiveCode: {
 				themes: ['github-dark', 'github-light'],
 				// Map languages for better syntax highlighting
-				langs: ['python', 'rust', 'go', 'javascript', 'typescript', 'bash', 'yaml', 'json', 'dockerfile', 'starlark']
+				langs: ['python', 'rust', 'go', 'javascript', 'typescript', 'bash', 'yaml', 'json', 'dockerfile'],
+				// Use Python grammar for Starlark since Starlark syntax is a subset of Python
+				shiki: {
+					langAlias: {
+						'starlark': 'python',
+						'star': 'python',
+						'bzl': 'python',
+						'bazel': 'python'
+					}
+				}
 			},
 			social: [
 				{
@@ -79,6 +88,9 @@ export default defineConfig({
 					label: 'Examples',
 					items: [
 						{ label: 'Basic Component', slug: 'examples/basic' },
+						{ label: 'Calculator (C++)', slug: 'examples/calculator' },
+						{ label: 'HTTP Service (Go)', slug: 'examples/http-service' },
+						{ label: 'Multi-Language System', slug: 'examples/multi-language' },
 					],
 				},
 				{
@@ -98,6 +110,8 @@ export default defineConfig({
 					label: 'Production',
 					items: [
 						{ label: 'Deployment Guide', slug: 'production/deployment-guide' },
+						{ label: 'OCI Publishing', slug: 'production/publishing' },
+						{ label: 'Performance Optimization', slug: 'production/performance' },
 					],
 				},
 				{

docs-site/astro.config.mjs

@@ -0,0 +1,125 @@
+"""Bazel rule for running documentation development server with live reload"""
+
+def _docs_dev_server_impl(ctx):
+    """Implementation of docs_dev_server rule for local development"""
+    
+    # Get jco toolchain for hermetic Node.js access  
+    jco_toolchain = ctx.toolchains["@rules_wasm_component//toolchains:jco_toolchain_type"]
+    node = jco_toolchain.node
+    npm = jco_toolchain.npm
+    
+    # Create runner script
+    runner = ctx.actions.declare_file(ctx.attr.name + "_runner.sh")
+    
+    # Input source files and package.json
+    source_files = ctx.files.srcs
+    package_json = ctx.file.package_json
+    
+    # Prepare source file list
+    source_paths = []
+    for src in source_files:
+        if src.path.startswith("docs-site/"):
+            source_paths.append(src.path)
+    
+    ctx.actions.write(
+        output = runner,
+        content = """#!/bin/bash
+set -euo pipefail
+
+# Store paths
+EXEC_ROOT="$(pwd)"
+PACKAGE_JSON="{package_json}"
+NODE="{node}"
+NPM="{npm}"
+
+# Create temporary workspace
+WORK_DIR="$(mktemp -d)"
+echo "🚀 Setting up documentation development server in: $WORK_DIR"
+
+# Cleanup on exit
+trap "echo '🛑 Shutting down dev server...'; rm -rf $WORK_DIR" EXIT
+
+# Copy package.json
+cp "$PACKAGE_JSON" "$WORK_DIR/package.json"
+
+# Copy all source files
+echo "📦 Copying source files..."
+{copy_commands}
+
+# Change to workspace
+cd "$WORK_DIR"
+
+# Install dependencies
+echo "📥 Installing dependencies..."
+$NPM install --no-audit --no-fund
+
+# Start development server
+echo "🌐 Starting Astro development server..."
+echo "📍 Documentation will be available at: http://localhost:4321"
+echo ""
+echo "Press Ctrl+C to stop the server"
+echo ""
+
+# Run dev server
+$NPM run dev
+""".format(
+            package_json = package_json.path,
+            node = node.path,
+            npm = npm.path,
+            copy_commands = "\n".join([
+                'if [[ "{src}" == docs-site/* ]]; then\n' +
+                '    rel_path="${{src#docs-site/}}"\n'.format(src=src) +
+                '    dest_file="$WORK_DIR/$rel_path"\n' +
+                '    dest_dir="$(dirname "$dest_file")"\n' +
+                '    mkdir -p "$dest_dir"\n' +
+                '    cp "{src}" "$dest_file"\n'.format(src=src) +
+                'fi'
+                for src in source_paths
+            ])
+        ),
+        is_executable = True,
+    )
+    
+    return [
+        DefaultInfo(
+            files = depset([runner]),
+            runfiles = ctx.runfiles(
+                files = source_files + [package_json, node, npm],
+            ),
+            executable = runner,
+        ),
+    ]
+
+docs_dev_server = rule(
+    implementation = _docs_dev_server_impl,
+    attrs = {
+        "srcs": attr.label_list(
+            allow_files = True,
+            mandatory = True,
+            doc = "Documentation source files",
+        ),
+        "package_json": attr.label(
+            allow_single_file = ["package.json"],
+            mandatory = True,
+            doc = "package.json file with dependencies",
+        ),
+    },
+    toolchains = ["@rules_wasm_component//toolchains:jco_toolchain_type"],
+    executable = True,
+    doc = """
+    Runs a development server for the documentation site with live reload.
+    
+    This rule starts an Astro dev server on http://localhost:4321 with hot module
+    replacement for rapid documentation development.
+    
+    Example:
+        docs_dev_server(
+            name = "docs_dev",
+            srcs = glob(["src/**/*", "public/**/*", "*.json", "*.mjs"]),
+            package_json = "package.json",
+        )
+        
+    Run with:
+        bazel run //docs-site:docs_dev
+    """,
+)