Documentation Collections

<ItemGroup>
  <DocumentationReference Include="../UserService/UserService.docsproj"
                         DestinationPath="services/users"
                         IntegrationType="Tabs"
                         Name="User Management" />
  <DocumentationReference Include="../OrderService/OrderService.docsproj"
                         DestinationPath="services/orders"
                         IntegrationType="Tabs"
                         Name="Order Processing" />
</ItemGroup>

{
  "name": "Microservices Platform",
  "tabs": [
    {
      "tab": "User Management",
      "href": "services/users",
      "pages": [
        "services/users/introduction",
        "services/users/api-reference/overview",
        ...
      ]
    },
    {
      "tab": "Order Processing",
      "href": "services/orders",
      "pages": [
        "services/orders/introduction",
        "services/orders/api-reference/overview",
        ...
      ]
    }
  ]
}

<ItemGroup>
  <DocumentationReference Include="../Core/Core.docsproj"
                         DestinationPath="core"
                         IntegrationType="Products"
                         Name="EasyAF Core" />
  <DocumentationReference Include="../Http/Http.docsproj"
                         DestinationPath="http"
                         IntegrationType="Products"
                         Name="HTTP Client" />
  <DocumentationReference Include="../Validation/Validation.docsproj"
                         DestinationPath="validation"
                         IntegrationType="Products"
                         Name="Validation Framework" />
</ItemGroup>

{
  "name": "EasyAF Product Suite",
  "navigation": {
    "products": [
      {
        "product": "EasyAF Core",
        "href": "core",
        "pages": [...],
        "groups": [...]
      },
      {
        "product": "HTTP Client",
        "href": "http",
        "pages": [...],
        "groups": [...]
      },
      {
        "product": "Validation Framework",
        "href": "validation",
        "pages": [...],
        "groups": [...]
      }
    ]
  }
}

docs/
   introduction.md          # Collection's own introduction
   architecture.md          # Collection's own architecture guide
   services/
      users/              # UserService documentation
         introduction.md
         api-reference/
      orders/             # OrderService documentation
         introduction.md
         api-reference/
      payments/           # PaymentService documentation
      notifications/      # NotificationService documentation
   docs.json               # Combined navigation

   Skipping documentation reference 'ServiceA.docsproj' because it uses 'DocFX' format.
Only 'Mintlify' documentation can be combined with Mintlify collections.
Cross-format documentation combination is not currently supported.

<DocumentationReference Include="../ServiceA/ServiceA.docsproj"
                       DestinationPath="services/service-a" />

{
  "pages": [
    "introduction",
    "api-reference/overview",
    {
      "group": "API Reference",
      "pages": [
        "api-reference/classes/user",
        "api-reference/classes/order"
      ]
    }
  ]
}

{
  "pages": [
    "services/service-a/introduction",
    "services/service-a/api-reference/overview",
    {
      "group": "API Reference",
      "pages": [
        "services/service-a/api-reference/classes/user",
        "services/service-a/api-reference/classes/order"
      ]
    }
  ]
}

# Build dependencies first
dotnet build ServiceA/ServiceA.docsproj
dotnet build ServiceB/ServiceB.docsproj

# Then build collection
dotnet build MicroservicesPlatform.docsproj

<CardGroup cols={2}>
  <Card title="Build Order Matters" icon="arrows-turn-right">
    Always build referenced projects before building the collection. Use solution build order or explicit build scripts.
  </Card>

  <Card title="Use Consistent Paths" icon="folder-tree">
    Organize `DestinationPath` consistently (e.g., all services under `services/`, all plugins under `plugins/`).
  </Card>

  <Card title="Keep References Simple" icon="minimize">
    Avoid circular references or overly complex reference chains. Keep your dependency graph flat and straightforward.
  </Card>

  <Card title="Version Together" icon="code-branch">
    When releasing, ensure referenced projects and collections use compatible versions of DotNetDocs.Sdk.
  </Card>

  <Card title="Test Independently" icon="vial">
    Each referenced project should work standalone before being added to a collection. Test them independently first.
  </Card>

  <Card title="Document the Collection" icon="book">
    Add a `README.md` or introduction page explaining the collection structure and how projects relate to each other.
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="MSBuild Integration" icon="gear">
    The `DocumentationReferenceResolverTask` runs during build to:

    1. Load each referenced `.docsproj` file
    2. Extract `DocumentationRoot` and `DocumentationType` properties
    3. Validate that documentation outputs exist
    4. Populate `ResolvedDocumentationReference` items with metadata

    These resolved items are passed to `GenerateDocumentationTask`, which populates `ProjectContext.DocumentationReferences`.
  </Accordion>

  <Accordion title="File Copying" icon="copy">
    The `DocumentationManager.CopyReferencedDocumentationAsync()` method:

    1. Iterates through each `DocumentationReference`
    2. Determines file patterns based on `DocumentationType`
    3. Copies files from `DocumentationRoot` to `DestinationPath`
    4. Skips files that already exist in the collection (collection wins)

    Copying happens **after** rendering completes.
  </Accordion>

  <Accordion title="Navigation Combining" icon="diagram-project">
    The `MintlifyRenderer.CombineReferencedNavigation()` method:

    1. Loads each reference's `docs.json` using `DocsJsonManager`
    2. Applies URL prefix using `ApplyUrlPrefix(DestinationPath)`
    3. Adds navigation to `Tabs` or `Products` array based on `IntegrationType`
    4. Saves the combined `docs.json` once at the end

    This happens **inside** `RenderAsync()` before saving, not as a separate step.
  </Accordion>

  <Accordion title="URL Prefix Application" icon="link">
    The `DocsJsonManager.ApplyUrlPrefix()` method recursively processes:

    - **String pages**: Prepends the prefix
    - **GroupConfig.Pages**: Recursively processes nested pages
    - **TabConfig.Pages**: Recursively processes nested pages
    - **DropdownConfig.Pages**: Recursively processes nested pages

    This ensures URL prefixes are applied at **all** nesting levels for correct navigation.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title=".docsproj Reference" icon="gear-complex-code" href="/guides/docsproj">
    Learn about all available MSBuild properties for documentation projects
  </Card>
  <Card title="Deployment" icon="conveyor-belt-boxes" href="/guides/deployment">
    Deploy your collection to Mintlify, GitHub Pages, or other hosting platforms
  </Card>
  <Card title="Pipeline Overview" icon="faucet-drip" href="/guides/pipeline">
    Understand how the documentation pipeline processes assemblies and content
  </Card>
  <Card title="Mintlify Provider" icon="sparkles" href="/providers/mintlify">
    Deep dive into Mintlify-specific features and configuration
  </Card>
</CardGroup>