### Example Installation Page Content (docs/installation.md)

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Presents an example of a content page, `docs/installation.md`, detailing installation steps and requirements. It includes front matter, headings, lists, and an embedded bash code block for verification, along with cross-reference links to other documentation sections.

```markdown
---
title: Installation
---

# Installation

This guide covers installing and setting up the system.

## System Requirements

- .NET 9 or later
- Git
- 4GB RAM minimum

## Installation Steps

1. Download the latest release
2. Extract to your desired location
3. Run the setup script

## Verification

Verify the installation:

```bash
your-command --version
```

## Next Steps

- [Configure your installation](xref://configuration.md)
- [Learn about advanced features](xref://advanced:index.md)
```

--------------------------------

### Verify System Installation Command

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

A generic command example to verify the successful installation of a system by checking its version. This snippet is typically found within installation guides.

```bash
your-command --version
```

--------------------------------

### `tanka-docs` New Project Setup Guide

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Provides a step-by-step guide for initializing a new `tanka-docs` project from scratch, including creating directories, initializing Git, setting up a default configuration, creating initial content, and starting the development server for live preview.

```bash
# Create a new project from scratch
mkdir my-docs && cd my-docs
git init
tanka-docs init

# Create documentation content
mkdir docs
echo "# Welcome" > docs/index.md
git add . && git commit -m "Initial docs"

# Start development
tanka-docs dev
```

--------------------------------

### Example Main Index Page Content (docs/index.md)

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Provides an example of the `docs/index.md` file, which serves as the main landing page for the documentation site. It includes front matter for the title, a main heading, introductory text, and internal links using Tanka Docs' cross-reference (xref) syntax.

```markdown
---
title: Welcome to My Documentation
---

# Welcome to My Documentation

This is the home page of your documentation site. 

## Quick Navigation

- [Installation](xref://installation.md) - Get up and running quickly
- [Configuration](xref://configuration.md) - Learn how to configure your project
- [Advanced Topics](xref://advanced:index.md) - Deep dive into advanced features

## Getting Started

Follow our [installation guide](xref://installation.md) to begin using the system.

## Need Help?

Check out our documentation sections for detailed information on specific topics.
```

--------------------------------

### Install Tanka Docs Global Tool via NuGet

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Installs the Tanka Docs generator as a .NET global tool from the NuGet package manager, which is the recommended installation method.

```bash
dotnet tool install --global Tanka.DocsGen
```

--------------------------------

### Configure Versioning for Tanka Docs

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Example YAML configuration for setting up multiple documentation versions based on Git branches and tags, mapping them to specific input paths.

```yaml
branches:
  main:
    input_path: [docs]
  develop:
    input_path: [docs]
tags:
  "v1.*":
    input_path: [docs]
  "v2.*":
    input_path: [docs]
```

--------------------------------

### Install Tanka Docs Global Tool from Source

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Clones the Tanka Docs repository, builds the project, and installs the tool globally from the local build artifacts. This method is typically used for development purposes.

```bash
git clone https://github.com/pekkah/tanka-docs-gen.git
cd tanka-docs-gen
dotnet pack -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts Tanka.DocsGen
```

--------------------------------

### Preview Tanka Docs Site with Development Server

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Starts a local development web server for live preview of the documentation. This command automatically builds the documentation, serves it (default port 8080), watches for file changes, and provides live browser reloading.

```bash
tanka-docs dev
```

--------------------------------

### Initialize Tanka Docs Project Configuration

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Runs the Tanka Docs initialization command to automatically set up the project. This command generates default configuration files (`tanka-docs.yml`, `tanka-docs-wip.yml`) and a customizable UI bundle (`ui-bundle/`).

```bash
tanka-docs init
```

--------------------------------

### Preview Tanka Docs Site with Custom Development Options

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Demonstrates how to use custom configuration files (e.g., `tanka-docs-wip.yml` for work-in-progress builds) or specify a custom port when running the Tanka Docs development server.

```bash
tanka-docs dev -f tanka-docs-wip.yml

tanka-docs dev --port 3000
```

--------------------------------

### Example Navigation File Content (docs/nav.md)

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Illustrates the structure of the `docs/nav.md` file, which defines the navigation hierarchy for the documentation site. It uses a simple Markdown list format with cross-reference links to content pages.

```markdown
* Documentation
  * [Welcome](xref://index.md)
  * [Installation](xref://installation.md)
  * [Configuration](xref://configuration.md)
  * [Advanced Topics](xref://advanced:index.md)
```

--------------------------------

### Enable Debug Output for Tanka Docs Build

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Command to run the Tanka Docs build tool with the `--debug` flag to get verbose output for troubleshooting purposes.

```bash
dotnet run --project src/DocsTool -- build --debug -f tanka-docs.yml
```

--------------------------------

### Create and Initialize Tanka Docs Project Directory

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Creates a new directory for the documentation project, navigates into it, and initializes a new Git repository with the 'main' branch. Tanka Docs sources content from Git repositories.

```bash
mkdir my-docs-project
cd my-docs-project
git init -b main
```

--------------------------------

### Tanka Docs Initialization Command Options

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Demonstrates various command-line options for the `tanka-docs init` command, allowing customization of the project name, source branch, selective file generation, force overwriting, and quiet mode.

```bash
tanka-docs init --project-name "My Documentation Site"

tanka-docs init --branch main

tanka-docs init --config-only

tanka-docs init --force

tanka-docs init --quiet
```

--------------------------------

### Create Documentation Content Directory

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Creates the `docs` directory, which is the default location for storing Markdown documentation files and other content for the Tanka Docs project.

```bash
mkdir docs
```

--------------------------------

### Installing and Testing Tanka.DocsGen Global Tool

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/CLAUDE.md

Instructions for installing the Tanka.DocsGen global tool from NuGet or building and installing it locally for development purposes. Also includes a command to test the functionality of the installed tool.

```Bash
# Install from NuGet (primary method)
dotnet tool install --global Tanka.DocsGen

# Or build and pack the global tool locally for development
dotnet pack -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts Tanka.DocsGen

# Test the installed tool
tanka-docs build -f ./tanka-docs.yml
```

--------------------------------

### Tanka Docs Quick Start Project Setup Commands

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/index.md

These commands demonstrate how to initialize a new Tanka Docs project, create a basic Markdown content file, build the static documentation site, and run a development server with live preview.

```Bash
# Initialize a new project (creates config and UI templates)
tanka-docs init

# Create your content
mkdir docs
echo "# Welcome" > docs/index.md

# Generate documentation
tanka-docs build

# Run in development mode with live preview
tanka-docs dev
```

--------------------------------

### Build Tanka Docs Documentation Site

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Executes the Tanka Docs build command, which processes the documentation content and generates the static site files. Successful execution results in output files located in the `_build/` directory.

```bash
tanka-docs build
```

--------------------------------

### Build Tanka Docs with Custom Output Directory

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Demonstrates how to specify a custom output directory for the built documentation using the `-o` flag with the `tanka-docs build` command.

```bash
tanka-docs build -o ./dist
```

--------------------------------

### YAML Code Example

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Example of a YAML configuration snippet, demonstrating syntax highlighting.

```yaml
title: "My Site"
description: "A documentation site"
sources:
  - name: "local"
    type: "local"
    path: "."
```

--------------------------------

### Verify .NET Installation and Retry Tanka Docs Tool Installation

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This snippet provides commands to check your .NET installation and then retry the global installation of the Tanka.DocsGen tool. It addresses issues where the tool might not be found or executed due to missing .NET runtime.

```bash
dotnet --version
```

```bash
dotnet tool install --global Tanka.DocsGen
```

--------------------------------

### C# Code Example

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Example of a C# class with properties and a method, demonstrating syntax highlighting.

```csharp
public class Example
{
    public string Name { get; set; }
    
    public void DoSomething()
    {
        Console.WriteLine($"Hello, {Name}!");
    }
}
```

--------------------------------

### Commit Initial Documentation Content to Git

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Stages all changes in the current directory and commits them to the Git repository with a descriptive message. This step is crucial as Tanka Docs sources its content directly from Git.

```bash
git add .
git commit -m "Initial documentation setup"
```

--------------------------------

### Default Tanka Docs Project Configuration (tanka-docs.yml)

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Shows the default structure and content of the `tanka-docs.yml` configuration file generated by the `tanka-docs init` command. It defines project metadata, content sources, output paths, UI bundle location, processing extensions, and development settings.

```yaml
name: "My Docs Project"
description: "Documentation for My Docs Project"

# Content sources - Git branches/tags for stable builds
sources:
  - source: git-branch
    branch: "main"
    path: docs/

# Output configuration
output_path: _build/
build_path: _site/

# UI configuration
ui_bundle: ui-bundle/

# Processing options
extensions:
  - include
  - xref

# Development settings (override in tanka-docs-wip.yml for WIP builds)
base_path: ""
```

--------------------------------

### JSON Code Example

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Example of a JSON object representing project metadata and dependencies, demonstrating syntax highlighting.

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "example": "^1.0.0"
  }
}
```

--------------------------------

### JavaScript Code Example

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Example of a JavaScript function for fetching data, demonstrating syntax highlighting.

```javascript
function fetchData(url) {
    return fetch(url)
        .then(response => response.json())
        .catch(error => console.error('Error:', error));
}
```

--------------------------------

### Configure Git Ignore for Tanka Docs Project

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Provides a sample `.gitignore` file to exclude Tanka Docs build artifacts and common OS files from version control.

```gitignore
# Tanka Docs build artifacts
_build/
gh-pages/

# OS files
.DS_Store
Thumbs.db
```

--------------------------------

### tanka-docs init Command Examples

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Practical examples demonstrating various ways to use the `tanka-docs init` command. These examples cover basic initialization, custom project names, specific branch settings, selective file creation, force overwriting, quiet mode, and initializing in a specific directory.

```bash
# Basic initialization in current directory
tanka-docs init

# Initialize with custom project name
tanka-docs init --project-name "My Documentation Site"

# Initialize with specific branch
tanka-docs init --branch main

# Only create configuration files (useful if you have custom UI)
tanka-docs init --config-only

# Only extract UI bundle (useful for UI customization)
tanka-docs init --ui-bundle-only

# Force overwrite existing files
tanka-docs init --force

# Quiet mode for automation scripts
tanka-docs init --quiet --project-name "Auto-Generated Docs"

# Initialize in a specific directory
tanka-docs init --output-dir ./my-docs-project
```

--------------------------------

### Create Cross-References in Tanka Docs

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Illustrates the Markdown syntax for creating internal links (cross-references) to other pages or sections within the Tanka Docs documentation.

```markdown
- [Configuration Guide](xref://configuration.md)
- [Advanced Section](xref://advanced-section:some-page.md)
```

--------------------------------

### tanka-docs build Command Examples

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Practical examples demonstrating various ways to use the `tanka-docs build` command. These examples cover basic builds, specifying custom configuration files, custom output directories, enabling debug output, setting a base href for subdirectory deployments, and combining multiple options.

```bash
# Basic build using default configuration
tanka-docs build

# Build with custom configuration file
tanka-docs build -f ./custom-config.yml

# Build with custom output directory
tanka-docs build -o ./custom-output

# Build with debug output
tanka-docs build --debug

# Build for deployment to subdirectory
tanka-docs build --base "/my-docs/"

# Combine multiple options
tanka-docs build -f ./config.yml -o ./dist --debug
```

--------------------------------

### Include External Source Code in Tanka Docs

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/01-getting-started/getting-started.md

Shows the Markdown syntax for including external source code files into Tanka Docs documentation using the `#include` directive and `xref` syntax.

```markdown
\#include::xref://src:example.cs
```

--------------------------------

### Install Tanka Docs Tool to User Directory to Resolve Permission Errors

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command provides a solution for permission-related installation failures by specifying a user-specific tool path. This avoids system-wide permission issues on macOS/Linux or when not running as administrator on Windows.

```bash
dotnet tool install --global Tanka.DocsGen --tool-path ~/.dotnet/tools
```

--------------------------------

### Example of Correct Tanka Docs Section YAML Configuration

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This YAML snippet provides an example of a `tanka-docs-section.yml` file, which defines a documentation section with its ID, title, type, and index page. It helps ensure that each section directory contains a properly formatted configuration file.

```yaml
id: "docs"
title: "Documentation"
type: "docs"
index_page: "index.md"
```

--------------------------------

### Tanka Docs: Checking the Installed Version

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Provides the command to quickly check the currently installed version of Tanka Docs, which is essential information when reporting issues or verifying updates.

```bash
tanka-docs --version
```

--------------------------------

### Example Tanka Docs YAML Configuration

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/02-project-structure/tanka-docs-yml.md

This example demonstrates a complete `tanka-docs.yml` file, defining site title, output path, index page, build directory, and how to configure documentation sources from specific Git branches and tags. It also includes a placeholder for extensions.

```YAML
base_path: "/"
title: "Tanka Docs Generator"
index_page: xref://root@master:index.md
output_path: "gh-pages"
build_path: "_build"
branches:
  master:
    input_path:
      - ui-bundle
      - docs-v2
      - src
tags:
  '1.*':
    input_path:
      - ui-bundle
      - docs-v2
      - src
```

--------------------------------

### Install Tanka Docs Global Tool

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/README.md

Instructions for installing Tanka Docs as a .NET global tool, either from NuGet (recommended) or from a local source for development purposes.

```bash
# Install from NuGet (recommended)
dotnet tool install --global Tanka.DocsGen

# Or install from local source (for development)
git clone https://github.com/pekkah/tanka-docs-gen.git
cd tanka-docs-gen
dotnet pack -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts Tanka.DocsGen
```

--------------------------------

### `tanka-docs` CI/CD Integration Examples

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Shows examples of `tanka-docs` commands suitable for continuous integration and continuous deployment pipelines. This covers building for production deployment with custom output directories and base URLs, and using environment-specific configuration files for different build scenarios.

```bash
# Build for production deployment
tanka-docs build --output ./dist --base "/docs/"
```

```bash
# Build with custom configuration for different environments
tanka-docs build -f ./config/production.yml -o ./dist
```

--------------------------------

### Complete Example: tanka-docs-section.yml Configuration

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/02-project-structure/tanka-docs-section.md

A comprehensive example of a `tanka-docs-section.yml` file, showcasing common configuration options for defining a documentation section, including its ID, title, index page, navigation, and included file patterns.

```YAML
id: examples
title: "Examples of Usage"
index_page: xref://basics.md
nav:
  - xref://nav.md
includes:
  - "**/*.puml"
```

--------------------------------

### Tanka Docs Init Command - First Time Setup

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/PLANNING.md

Illustrates the interactive `tanka-docs init` command for a new project, showing the prompts for project name and default branch, the files to be created (`tanka-docs.yml`, `tanka-docs-wip.yml`, `ui-bundle/`), and the successful initialization message with a summary of the generated configuration files.

```bash
$ tanka-docs init
✓ Tanka Docs Project Initialization

Checking Git repository... ✓
Current directory: /path/to/my-project
Project name [my-project]: My Documentation Site
Default branch [main]: ⏎

The following will be created:
  • tanka-docs.yml (main configuration)
  • tanka-docs-wip.yml (development configuration)  
  • ui-bundle/ (default UI templates)

Continue? (y/N): y

✓ Created tanka-docs.yml
✓ Created tanka-docs-wip.yml
✓ Extracted UI bundle to ./ui-bundle/
✓ Project initialized successfully!

📝 Configuration Review:

The following files have been created:

┌─ tanka-docs.yml ──────────────────────────────────────┐
│ title: "My Documentation Site Documentation"          │
│ output_path: "output"                                 │
│ build_path: "_build"                                  │
│ index_page: xref://docs@main:index.md                 │
│                                                       │
│ ui_bundle: "./ui-bundle"                              │
│                                                       │
│ branches:                                             │
│   main:                                               │
│     input_path:                                       │
│       - docs        ← Your documentation files       │
│       - _partials   ← Shared content (optional)      │
└───────────────────────────────────────────────────────┘

┌─ tanka-docs-wip.yml ──────────────────────────────────┐
│ base_path: "/"                                        │
│ title: "My Documentation Site Documentation - WIP"    │
│ index_page: xref://docs@HEAD:index.md                 │
│ output_path: "gh-pages"                               │
│ build_path: "_build"                                  │
│                                                       │
│ ui_bundle: "./ui-bundle"                              │
│                                                       │
│ branches:                                             │
│   HEAD:                                               │
│     input_path:                                       │
│       - ui-bundle   ← UI customization               │
│       - docs        ← Your documentation files       │
│       - src         ← Source code for includes       │
└───────────────────────────────────────────────────────┘

🔧 Customize Your Configuration:
Edit these files to match your project structure:
• Update input_path directories to match your layout
• Add or remove paths as needed for your content
• The paths are relative to your project root

Next steps:
  1. Review and customize input_path settings above
  2. Create your documentation directories  
  3. Add your first documentation section
  4. Run 'tanka-docs build' to generate your site
  5. Use 'tanka-docs build -f tanka-docs-wip.yml' for development builds
```

--------------------------------

### Serve Tanka Docs Locally with dotnet-serve

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/README.md

Instructions to install the `dotnet-serve` global tool and use it to host the generated static documentation locally, allowing for easy preview and testing.

```bash
dotnet tool install --global dotnet-serve
cd output
dotnet serve
```

--------------------------------

### Example of Correct Tanka Docs YAML Configuration Syntax

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This YAML snippet illustrates the correct syntax for a `tanka-docs.yml` configuration file, demonstrating proper indentation, key-value pairs, and list formatting. It serves as a reference to avoid common YAML parsing errors like mixed tabs/spaces or missing colons.

```yaml
title: "My Site"
sources:
  - name: "local"
    type: "local"
    path: "."
```

--------------------------------

### Install Tanka Docs CLI from Source

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Installs the Tanka Docs command-line interface globally by cloning the repository, building it, and then installing it as a .NET global tool from the local artifacts. This method is typically used for development or contributing to the project.

```bash
git clone https://github.com/pekkah/tanka-docs-gen.git
cd tanka-docs-gen
dotnet pack -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts Tanka.DocsGen
```

--------------------------------

### Install Tanka Docs CLI via NuGet

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Installs the Tanka Docs command-line interface globally using the .NET tool manager from NuGet, which is the recommended method for most users.

```bash
dotnet tool install --global Tanka.DocsGen
```

--------------------------------

### Install Tanka Docs .NET Global Tool

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/index.md

This command installs the Tanka Docs documentation generator as a global .NET tool, making it accessible from any directory in your terminal.

```Bash
dotnet tool install --global Tanka.DocsGen
```

--------------------------------

### Tanka Docs: Building with Multiple Environment Configurations

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Demonstrates how to use different configuration files for development and production environments with Tanka Docs, allowing for distinct output directories and base paths tailored to specific deployment needs.

```bash
# Development
tanka-docs build -f config/dev.yml -o ./dev-output

# Production  
tanka-docs build -f config/prod.yml -o ./dist --base "/docs/"
```

--------------------------------

### `tanka-docs dev` Command Syntax and Options

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Documents the `tanka-docs dev` command, its syntax, and available options like `--file` and `--port`. It explains how to run a development server for live preview, including examples for default, custom port, and custom configuration usage.

```bash
tanka-docs dev [options]
```

```bash
# Run dev server with default settings
tanka-docs dev
```

```bash
# Run dev server on a custom port
tanka-docs dev --port 8080
```

```bash
# Use a custom configuration file
tanka-docs dev -f ./custom-config.yml
```

--------------------------------

### Example of Correct Tanka Docs Markdown Include Syntax

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This Markdown snippet illustrates the correct syntax for including external files, such as source code, into a Tanka Docs page. It ensures that the `\#include::xref://` directive is properly formatted to locate and embed content.

```markdown
\#include::xref://src:Program.cs
```

--------------------------------

### Example of Correct Tanka Docs Navigation YAML Configuration

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This YAML snippet shows how to correctly define navigation entries in Tanka Docs, ensuring that the `page` value matches the actual filename. It helps resolve issues where pages are not found due to incorrect references in the navigation structure.

```yaml
navigation:
  - title: "Installation"
    page: "installation.md"  # Must match actual filename
```

--------------------------------

### Markdown: Correct Code Block Language Identifiers

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Shows the importance of using correct language identifiers for code blocks to enable proper syntax highlighting. Provides an example of a correct C# identifier versus an incorrect one.

```markdown
<!-- Good -->
```csharp
// C# code
```

<!-- Bad -->
```c#
// Wrong identifier
```
```

--------------------------------

### `tanka-docs` Building with Multiple Configurations

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Illustrates how to use `tanka-docs` to build documentation using different configuration files for distinct environments. Examples include separate builds for development and production, each with its own configuration file, output directory, and base path.

```bash
# Development build
tanka-docs build -f ./config/dev.yml -o ./dev-output
```

```bash
# Production build
tanka-docs build -f ./config/prod.yml -o ./prod-output --base "/api-docs/"
```

--------------------------------

### Example of Correct Tanka Docs Markdown Cross-Reference Syntax

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This Markdown snippet demonstrates the correct syntax for creating cross-references to other documentation pages within Tanka Docs. It ensures that the `xref://` path accurately points to the target filename, preventing 'file not found' errors for internal links.

```markdown
[Link](xref://installation.md)  # Must match actual filename
```

--------------------------------

### `tanka-docs` Getting Help and Command Options

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Explains how to access help documentation for the `tanka-docs` CLI tool. This includes showing available commands and general options, as well as specific help for subcommands like `init`, `build`, and `dev` to understand their usage.

```bash
# Show available commands and options
tanka-docs --help
```

```bash
# Show help for specific command
tanka-docs init --help
```

```bash
# Show help for specific command
tanka-docs build --help
```

```bash
# Show help for specific command
tanka-docs dev --help
```

--------------------------------

### Example of Correct Tanka Docs Markdown Escaped Include Syntax

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This Markdown snippet demonstrates the correct syntax for escaping an include directive, preventing Tanka Docs from processing it. It ensures that the `\#include::` string is rendered literally rather not being interpreted as an instruction.

```markdown
\#include::xref://src:Program.cs
```

--------------------------------

### Running Tanka Documentation Generator in Development Mode

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/CLAUDE.md

Commands for local development and 'dogfooding' the documentation generator. Includes options for live reload during documentation changes and building the site for testing purposes.

```Bash
# Development mode with live reload for documentation changes
dotnet run --project ./src/DocsTool/ -- dev -f ./tanka-docs-wip.yml

# Build documentation site (prefer this when testing changes)
dotnet run --project ./src/DocsTool/ -- build -f ./tanka-docs-wip.yml
```

--------------------------------

### Markdown Headers

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Demonstrates the syntax for defining headers from H1 to H6 in Markdown.

```markdown
# H1 Header
## H2 Header  
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header
```

--------------------------------

### Tanka Docs: Updating to the Latest Version

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Explains how to update the Tanka Docs global .NET tool to its latest available version, ensuring access to new features, bug fixes, and performance improvements.

```bash
dotnet tool update --global Tanka.DocsGen
```

--------------------------------

### Markdown Ordered Lists

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Demonstrates how to create ordered lists with numerical prefixes and nested ordered items.

```markdown
1. First item
2. Second item
   1. Nested item
   2. Another nested item
3. Third item
```

--------------------------------

### Markdown Tables

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for creating basic tables with columns and rows.

```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |
```

--------------------------------

### Tanka Docs Example Project Directory Structure

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/index.md

This snippet illustrates the recommended file and directory organization for a Tanka Docs project, showing the placement of main configuration, documentation sections, and source code that can be included.

```Text
my-project/
├── tanka-docs.yml              # Main configuration
├── docs/
│   ├── tanka-docs-section.yml  # Section configuration
│   ├── index.md                # Section home page
│   ├── getting-started.md
│   └── advanced/
│       └── configuration.md
├── api-docs/
│   ├── tanka-docs-section.yml
│   └── reference.md
└── src/
    └── MyProject/
        └── Program.cs          # Can be included in docs
```

--------------------------------

### Running Specific Tanka Test Projects

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/CLAUDE.md

Commands to execute tests for specific components of the Tanka Documentation Generator, such as the DocsTool or FileSystem modules, using the dotnet test command with xUnit.

```Bash
dotnet test tests/DocsTool.Tests/
dotnet test tests/FileSystem.Tests/
```

--------------------------------

### Markdown Unordered Lists

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Illustrates the creation of unordered lists and nested list items using hyphens.

```markdown
- Item 1
- Item 2
  - Nested item
  - Another nested item
- Item 3
```

--------------------------------

### List All Existing Git Tags

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command lists all tags present in the Git repository. It helps verify if tags have been correctly created and are available for Tanka Docs to detect versions.

```bash
git tag -l
```

--------------------------------

### Tanka Docs Cross-References

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for creating links to other documentation pages or sections, including specific versions, using `xref://`.

```markdown
[Link to same section](xref://other-page.md)
[Link to different section](xref://section-id:page.md)
[Link to specific version](xref://section-id@1.0.0:page.md)
```

--------------------------------

### Example YAML: Configure Navigation for Tanka Docs Section

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/02-project-structure/tanka-docs-section.md

Demonstrates how to define the navigation structure for a documentation section using a list of `xref` links to Markdown files. These files contain the actual navigation links.

```YAML
nav:
  - xref://nav.md
  - xref://advanced-nav.md
```

--------------------------------

### `tanka-docs` Troubleshooting Common Issues

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Provides guidance on resolving common issues encountered with `tanka-docs`, such as configuration file not found, build failures, and permission errors. It includes an example of a configuration error message and suggests debugging steps and solutions.

```bash
Could not load configuration: 'tanka-docs.yml'
```

--------------------------------

### Building and Testing Tanka Documentation Generator

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/CLAUDE.md

Commands to compile the Tanka project, run all tests, and generate test coverage reports. This section covers standard .NET build and test operations for the documentation generator.

```Bash
# Build the project
dotnet build

# Full build with tests and packaging
./build.ps1

# Run all tests
dotnet test

# Run tests with coverage in artifacts directory
dotnet test --logger trx --results-directory ./artifacts
```

--------------------------------

### Markdown Task Lists

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for creating interactive task lists with checkboxes for completed and incomplete items.

```markdown
- [x] Completed task
- [ ] Incomplete task
- [x] Another completed task
```

--------------------------------

### Build Tanka Docs Static Site

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/README.md

Commands to build the documentation, generating static HTML files. This can be executed either by using the globally installed Tanka Docs tool or by running directly from the source project.

```bash
# If installed as global tool:
tanka-docs build

# Or run directly from source:
dotnet run --project ./src/DocsTool/ -- build
```

--------------------------------

### Update Tanka Docs CLI from Source

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Updates the globally installed Tanka Docs command-line interface when it was originally installed from source. This involves pulling the latest changes from the repository, rebuilding the project, and then updating the tool from local artifacts.

```bash
git pull
dotnet pack -c Release -o ./artifacts
dotnet tool update --global --add-source ./artifacts Tanka.DocsGen
```

--------------------------------

### Markdown Fenced Code Blocks

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Shows how to create fenced code blocks with language specifiers for syntax highlighting.

```markdown
```javascript
function hello() {
    console.log("Hello, world!");
}
```
```

--------------------------------

### Markdown Definition Lists

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for defining terms and their corresponding definitions in a list format.

```markdown
Term 1
:   Definition 1

Term 2  
:   Definition 2a
:   Definition 2b
```

--------------------------------

### Tanka Docs: Setting Base Path for Subdirectory Deployment

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Explains how to configure the base path for Tanka Docs builds to resolve 404 errors when deploying to a subdirectory, ensuring links are correctly generated relative to the deployment root.

```bash
tanka-docs build --base "/my-docs/"
```

--------------------------------

### Tanka Docs Include Directives

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for including content from other files, including specific sections or partials, using `\#include::`.

```markdown
\#include::xref://src:Program.cs
\#include::xref://src:Program.cs?s=MyNamespace.MyClass.MyMethod
\#include::xref://_partials:common-notice.md
```

--------------------------------

### Initialize Git Repository and Perform Initial Commit

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

These commands initialize a new Git repository in the current directory, stage all files, and create an initial commit. This is crucial for Tanka Docs to correctly detect repository information and manage versions, resolving 'repository not found' errors.

```bash
git init
git add .
git commit -m "Initial commit"
```

--------------------------------

### Verify Existence of Referenced Markdown Files

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command checks if a specific Markdown file, such as `installation.md`, exists in the expected directory. It helps troubleshoot 'file not found' errors when Tanka Docs attempts to resolve page references.

```bash
ls -la docs/installation.md
```

--------------------------------

### Tanka Docs Init Command - Git Repository Error

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/PLANNING.md

Shows an example of the error message displayed when `tanka-docs init` is executed in a directory that is not a Git repository, providing clear guidance to the user.

```bash
$ tanka-docs init
✗ Error: Current directory is not a Git repository

Tanka Docs requires a Git repository to function properly.
```

--------------------------------

### Markdown Highlighting

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for highlighting text within Markdown content.

```markdown
==highlighted text==
```

--------------------------------

### Markdown Keyboard Keys

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for representing keyboard key combinations in Markdown.

```markdown
Press ++ctrl+alt+del++ to restart.
```

--------------------------------

### Tanka Docs CLI: `dev` Command Reference

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/index.md

Documentation for the `tanka-docs dev` command, which starts a local development server. This server provides a live preview and hot-reloading capabilities for efficient documentation development.

```APIDOC
tanka-docs dev
  Description: Starts a local development server with live preview and hot-reloading.
```

--------------------------------

### Markdown Links and Images

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for creating inline links with optional titles and embedding images with alt text and optional titles.

```markdown
[Link text](https://example.com)
[Link with title](https://example.com "Link title")
![Image alt text](path/to/image.png)
![Image with title](path/to/image.png "Image title")
```

--------------------------------

### Markdown Footnotes

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for adding footnotes to text and defining their content.

```markdown
Here's a sentence with a footnote[^1].

[^1]: This is the footnote content.
```

--------------------------------

### Markdown Admonitions/Callouts

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for creating styled admonition blocks (notes, warnings, tips, etc.) with optional custom titles.

```markdown
!!! note "Optional Title"
    This is a note admonition.

!!! warning
    This is a warning without a custom title.

!!! tip "Pro Tip"
    This is a tip with a custom title.
```

--------------------------------

### Example Tanka Docs Project Structure

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/README.md

An illustrative directory structure for a Tanka Docs project, showcasing the typical organization of configuration files, documentation sections, shared content (partials), and source code directories for includes.

```plaintext
my-project/
├── tanka-docs.yml              # Main configuration
├── docs/                       # Documentation section
│   ├── tanka-docs-section.yml  # Section configuration
│   ├── index.md               # Documentation files
│   └── getting-started.md
├── _partials/                  # Shared content
│   ├── tanka-docs-section.yml
│   └── common-notice.md
└── src/                        # Source code (for includes)
    └── Program.cs
```

--------------------------------

### Markdown Text Formatting

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Shows how to apply bold, italic, bold and italic, strikethrough, and inline code formatting to text in Markdown.

```markdown
**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`
```

--------------------------------

### Markdown Block Math (LaTeX)

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for embedding block-level mathematical expressions using LaTeX in Markdown.

```markdown
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

--------------------------------

### Tanka Docs Section File Organization Example

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/02-project-structure/file-system.md

Demonstrates a logical file organization within a Tanka Docs section, showing how to structure index pages, top-level topics, grouped topics in subdirectories, and supporting materials.

```plaintext
user-guide/
├── tanka-docs-section.yml
├── index.md                    # Section home
├── installation.md             # Top-level topics
├── configuration.md
├── advanced/                   # Grouped topics
│   ├── custom-templates.md
│   ├── performance.md
│   └── security.md
└── examples/                   # Supporting materials
    ├── basic-config.yml
    └── advanced-config.yml
```

--------------------------------

### Update Tanka Docs CLI via NuGet

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/cli-reference.md

Updates the globally installed Tanka Docs command-line interface to the latest version available on NuGet, ensuring you have the most recent features and bug fixes.

```bash
dotnet tool update --global Tanka.DocsGen
```

--------------------------------

### Create a Git Tag for Version Detection

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command creates a lightweight Git tag, `v1.0.0`, which Tanka Docs can use to detect versions within the repository. Creating at least one tag is essential for resolving 'no versions found' errors.

```bash
git tag v1.0.0
```

--------------------------------

### Markdown Fenced Code Blocks with Line Numbers

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Demonstrates how to add line numbers to fenced code blocks using the `.line-numbers` attribute.

```markdown
```csharp {.line-numbers}
public class Example
{
    public void Method() { }
}
```
```

--------------------------------

### Create a Git Branch for Versioning

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command creates a new Git branch, `docs-v1.0`, which can be used by Tanka Docs for versioning purposes. Using branches is an alternative to tags for managing different documentation versions.

```bash
git checkout -b docs-v1.0
```

--------------------------------

### Build .NET Project to Verify Code Compilation

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command compiles the .NET project, which is necessary to ensure that the C# source files are valid and that Roslyn can correctly parse symbols. A successful build confirms that symbols are well-defined and accessible for Tanka Docs includes.

```bash
dotnet build
```

--------------------------------

### Specify Alternate Output Directory for Tanka Docs Build

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command instructs Tanka Docs to build the documentation into a different output directory, `./my-output`, using the `-o` flag. This provides a workaround for 'permission denied' errors by allowing the user to choose a directory where they have write access.

```bash
tanka-docs build -o ./my-output
```

--------------------------------

### Markdown Inline Math (LaTeX)

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for embedding inline mathematical expressions using LaTeX within Markdown text.

```markdown
The formula is $E = mc^2$.
```

--------------------------------

### Markdown Front Matter

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/03-writing-content/markdown.md

Syntax for adding YAML front matter to Markdown pages for metadata like title, description, author, date, and tags.

```markdown
---
title: "Page Title"
description: "Page description for SEO"
author: "Author Name"
date: "2024-01-15"
tags: ["tag1", "tag2"]
---

# Your content starts here
```

--------------------------------

### Tanka Docs: Redirecting Debug Output to a Log File

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Shows how to capture the detailed debug output of a Tanka Docs build command and redirect it to a log file, which is useful for later analysis or sharing troubleshooting information.

```bash
tanka-docs build --debug > build.log 2>&1
```

--------------------------------

### Embedding Code Snippets in Markdown

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/README.md

Demonstrates the Markdown syntax for including entire C# files or specific symbols into documentation using the `#include` directive, leveraging Roslyn integration for live code examples.

```markdown
```csharp
# Include entire file
\#include::xref://src:Program.cs
```
```

--------------------------------

### Verify Existence of Referenced Include Files

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command checks if a specific file, like `src/Program.cs`, exists in the expected location for inclusion. It helps diagnose 'include file not found' errors by confirming the physical presence of the referenced content.

```bash
ls -la src/Program.cs
```

--------------------------------

### Tanka Docs: Cleaning Build Directory to Improve Build Times

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Describes how to remove the `_build/` directory to ensure a clean slate for subsequent builds, which can help resolve slow build times by preventing incremental build issues or stale artifacts.

```bash
rm -rf _build/
```

--------------------------------

### Run Tanka Docs Gen in Development Mode

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/CONTRIBUTING.md

Starts the Tanka Docs Gen tool in development mode for live preview and hot-reloading of documentation, using the work-in-progress configuration file. This is the recommended workflow for documentation changes.

```bash
dotnet run --project .\\src\\DocsTool\\ -- dev -f .\\tanka-docs-wip.yml
```

--------------------------------

### APIDOC: tanka-docs-section.yml Configuration Fields

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/02-project-structure/tanka-docs-section.md

Reference for the configurable fields within the `tanka-docs-section.yml` file, used to structure documentation sections. Each field's purpose, type, requirement status, and examples are detailed.

```APIDOC
id:
  Purpose: A unique identifier for the section. This ID is used when creating cross-references (`xref`) to content within this section from other parts of your documentation.
  Type: String
  Required: Yes
  Example: `getting-started`

title:
  Purpose: The display title for the section. This is often used in navigation menus and page headers.
  Type: String
  Required: Yes
  Example: `Getting Started Guide`

index_page:
  Purpose: Specifies the main entry page for the section. This is typically the first page a user sees when they navigate to the section.
  Type: `xref`
  Required: No
  Default: `xref://index.md`
  Example: `xref://introduction.md`

nav:
  Purpose: A list of `xref` links to Markdown files that define the navigation structure for the section. These files contain lists of links that will be rendered as the section's navigation menu.
  Type: `List of xrefs`
  Required: No
  Example:
    nav:
      - xref://nav.md
      - xref://advanced-nav.md

type:
  Purpose: The type of the section, which can influence how it's processed.
  Type: String
  Required: No
  Default: `doc`
  Example: `doc`

includes:
  Purpose: A list of glob patterns to include files in the section.
  Type: `List of Strings`
  Required: No
  Example:
    includes:
      - "**/*.cs"

extensions:
  Purpose: Configures extensions specific to this section. The structure is dependent on the extension being used.
  Type: Object
  Required: No
```

--------------------------------

### Example YAML: Include Files in Tanka Docs Section

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/02-project-structure/tanka-docs-section.md

Illustrates how to specify files to be included in a documentation section using glob patterns. This allows for selective inclusion of content based on file types or paths.

```YAML
includes:
  - "**/*.cs"
```

--------------------------------

### Verify Tanka Docs Configuration File Existence and Specify Path

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

These commands help diagnose and resolve 'configuration file not found' errors. They allow checking for the `tanka-docs.yml` file's presence, verifying the current working directory, and explicitly specifying the configuration file's path during the build process.

```bash
ls -la tanka-docs.yml
```

```bash
pwd
```

```bash
tanka-docs build -f path/to/tanka-docs.yml
```

--------------------------------

### Tanka Docs: Enabling Debug Mode for Detailed Troubleshooting

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

Explains how to activate debug mode during a Tanka Docs build to obtain comprehensive diagnostic information, including processing steps, file resolution, error stack traces, and performance timings, which is crucial for in-depth troubleshooting.

```bash
tanka-docs build --debug
```

--------------------------------

### Tanka Docs NuGet Package Publication & Distribution

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/PLANNING.md

This section details the completed efforts for publishing the Tanka documentation tool to NuGet.org. It highlights the automated processes and successful distribution, making the tool easily accessible for global installation and updates.

```APIDOC
Status: Completed
Priority: High

Completed Features:
- Automated NuGet packaging via GitHub workflows
- Release workflow automation configured
- Published to NuGet.org with proper versioning
- Documentation updated to reflect NuGet installation as primary method
```

--------------------------------

### Check Permissions of Tanka Docs Output Directory

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command lists the permissions of the specified output directory, such as `gh-pages/`. It helps diagnose 'permission denied' errors by showing if the current user has the necessary read and write access to the directory.

```bash
ls -la gh-pages/
```

--------------------------------

### Run Tanka Docs Build in Debug Mode to List Available Roslyn Symbols

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command executes the Tanka Docs build process with the `--debug` flag, which provides detailed information, including a list of available Roslyn symbols. This helps in identifying the correct fully qualified name for symbols when troubleshooting 'symbol not found' errors.

```bash
tanka-docs build --debug
```

--------------------------------

### Tanka Docs Init Command - Existing Project

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/PLANNING.md

Demonstrates the `tanka-docs init` command when run in an existing project, showing how it detects existing files and prompts to create missing ones, such as `tanka-docs-wip.yml` and `ui-bundle/`.

```bash
$ tanka-docs init
✓ Existing files detected

Found: tanka-docs.yml
Missing: tanka-docs-wip.yml, ui-bundle/

Create missing files? (y/N): y
✓ Created tanka-docs-wip.yml
✓ Extracted UI bundle to ./ui-bundle/
✓ Initialization complete!
```

--------------------------------

### Run Tanka Docs Build in Debug Mode for Detailed Processing Logs

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This command executes the Tanka Docs build process with the `--debug` flag, providing verbose output that can help identify the root cause of include file issues or other build problems. The detailed logs offer insights into file resolution and processing steps.

```bash
tanka-docs build --debug
```

--------------------------------

### Tanka Docs Init Command Structure

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/PLANNING.md

Illustrates the basic command-line structure for the `tanka-docs init` command, showing how options are typically appended.

```bash
tanka-docs init [options]
```

--------------------------------

### CSS: Custom Styling for Documentation UI

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/README.md

This CSS snippet provides an example of custom styling for Tanka Docs Gen. It defines CSS variables for primary and background colors, allowing users to easily customize the look and feel of their generated documentation.

```CSS
/* ui-bundle/css/custom.css */
:root {
  --primary-color: #007acc;
  --background-color: #f8f9fa;
}
```

--------------------------------

### Configure Tanka Docs for Local-Only Source Without Git

Source: https://github.com/pekkah/tanka-docs-gen/blob/master/docs-v2/04-advanced/troubleshooting.md

This YAML snippet configures Tanka Docs to use a local source type, which is suitable for documentation projects that do not rely on a Git repository for versioning or content management. It resolves Git-related errors when Git is not intended for use.

```yaml
sources:
  - name: "local"
    type: "local"
    path: "."
```