Swift DocC

https://github.com/swiftlang/swift-docc
Admin
Swift-DocC is a documentation compiler for Swift frameworks and packages that makes it easy to write...
Tokens:46,680
Snippets:754
Trust Score:9.4
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Tutorial with Assessments

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Assessments/Assessments.md

This example demonstrates how to structure a tutorial with an assessment section, including multiple-choice questions and justifications for feedback.

```swift
@Tutorial(time: 30) {
    
    ... 

    @Assessments {
        @MultipleChoice {
            What element did you use to add space around and between your views?

            @Choice(isCorrect: false) {
                A state variable.

                @Justification(reaction: "Try again!") {
                    Remember, it's something you used to arrange views vertically.
                }
            }

            @Choice(isCorrect: true) {
                A `VStack` with trailing padding.

                @Justification(reaction: "That's right!") {
                    A `VStack` arranges views in a vertical line.
                }
            }

            @Choice(isCorrect: false) {
              
              ... 
              
            }
        }  
    }
}
```

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

### Step with Context and Code Example

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Steps/Step/Step.md

Shows how to provide preceding text for context and include a code snippet within a tutorial step.

```swift
The following steps display your customized sloth view in the preview.

    @Step {
        Add the `sloth` parameter to initialize the `CustomizedSlothView` in the preview provider, and pass a new `Sloth` instance for the value.
        
        @Code(name: "CustomizedSlothView.swift", file: 01-creating-code-02-07.swift) {
            @Image(source: preview-01-creating-code-02-07.png, alt: "A portrait of a generic sloth displayed in the center of the canvas.")
        }
    }
```

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

### Tutorial Code Step Example

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Steps/Step/Code.md

This example shows how to use the Code directive within a Step to display a Swift code file and an associated image preview. The `name` parameter specifies the file name shown to the reader, and the `file` parameter points to the actual code file in the documentation catalog.

```swift
@Tutorial(time: 30) {
    
    ...
    
    @Section(title: "Add a customization view") {
        
        ...
        
        @Steps {

            ...

            @Step {
                Add the `sloth` parameter to initialize the `CustomizedSlothView` in the preview provider, and pass a new `Sloth` instance for the value.
                
                @Code(name: "CustomizedSlothView.swift", file: "01-creating-code-02-07.swift") {
                    @Image(source: preview-01-creating-code-02-07, alt: "A portrait of a generic sloth displayed in the center of the canvas.")
                }
            }

            @Step {
                Set the preview provider sloth's `name` to `"Super Sloth"`, `color` to `.blue`, and `power` to `.ice`.
                
                @Code(name: "CustomizedSlothView.swift", file: "01-creating-code-02-08.swift") {
                    @Image(source: preview-01-creating-code-02-08, alt: "A portrait of an ice sloth on top, followed by four power icons below. The power icons, clockwise from top left, include: ice, fire, wind, and lightning. The ice icon is selected.")
                }    
            
                ...
            }
        }
    }
}
```

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

### Install Executable

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/CMakeLists.txt

Installs the 'docc' executable to the runtime destination directory.

```cmake
install(TARGETS docc
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
```

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

### Tutorial Section Example

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section.md

Demonstrates the structure of a tutorial with a section that includes content, media, and steps. Use this to organize a unit of work within a tutorial.

```swift
@Tutorial(time: 30) {
    
    ...
    
    @Section(title: "Add a customization view") {
        @ContentAndMedia {
            Add the ability for users to customize sloths and select their powers.
            
            @Image(source: 01-creating-section2.png, alt: "An outline of a sloth surrounded by four power type icons. The power type icons are arranged in the following order, clockwise from the top: fire, wind, lightning, and ice.")
        }
        
        @Steps {
            @Step {
                Create a new SwiftUI View file named `CustomizedSlothView.swift`.
                
                @Code(name: "CustomizedSlothView.swift", file: 01-creating-code-02-01.swift) {
                    @Image(source: preview-01-creating-code-02-01.png, alt: "A screenshot as it would appear on iPhone, with the text, Hello, World!, centered in the middle of the display.")
                }
            }
            
            @Step {
                
                ...
                
            }
            
            ...
 
        }
    }
}
```

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

### Preview Documentation with DocC

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Convert documentation and start a local web server for previewing. This command monitors for changes and updates the preview automatically.

```bash
swift run docc preview Sources/SwiftDocC/SwiftDocC.docc \
  --fallback-display-name SwiftDocC \
  --fallback-bundle-identifier org.swift.SwiftDocC \
  --fallback-bundle-version 1.0.0 \
  --additional-symbol-graph-dir .build/swift-docc-symbol-graphs
```

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

### Tutorial with Assessments

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/building-an-interactive-tutorial.md

An example of a complete tutorial page including an introduction, a section with steps, and an assessment with multiple-choice questions to test reader knowledge.

```docc
@Tutorial(time: 20) {
    @Intro(title: "Add a title for your tutorial page here.") {
        Add engaging introduction text here.
        
        @Image(source: tutorial-introduction-image-filename, alt: "Add an accessible description for your image here.")
    }
    
    @Section(title: "Add a section title here") {
        @ContentAndMedia {
            Add some content here to introduce the steps that follow.
            
            @Image(source: section-image-filename, alt: "Add an accessible description for your image here.")
        }
        
        @Steps {
            @Step {
                Provide text for a step here.
                @Image(source: step1-image-filename, alt: "Add an accessible description for your image here.")
            }
            @Step {
                Provide text for another step here.
                @Image(source: step2-image-filename, alt: "Add an accessible description for your image here.")
            }
        }
    }

    @Assessments {
        @MultipleChoice {
            Add a question to test the reader's knowledge here.

            @Choice(isCorrect: false) {
                Add an incorrect answer here.

                @Justification(reaction: "Try again!") {
                    Add a hint that helps direct the reader to the right answer.
                }
            }

            @Choice(isCorrect: true) {
                Add the correct answer here.

                @Justification(reaction: "That's right!") {
                    Add some text that reinforces the right answer.
                }
            }

            @Choice(isCorrect: false) {
                Add another incorrect answer here.

                @Justification(reaction: "Try again!") {
                    Add another hint that helps direct the reader to the right answer.
                }
            }
        }
    }
}
```

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

### Install SwiftDocC Target

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/CMakeLists.txt

Installs the SwiftDocC target (executable, library, and archive) to the appropriate directories if BUILD_SHARED_LIBS is enabled.

```cmake
if(BUILD_SHARED_LIBS)
  install(TARGETS SwiftDocC
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
endif()
```

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

### Create a Swift Code Snippet File

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

Place your Swift code examples in the `Snippets` directory at the root of your project. Each file in this directory is treated as a separate snippet.

```swift
import Foundation

print("Hello")
```

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

### Tutorial Template Structure

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/building-an-interactive-tutorial.md

Use this template to create a new tutorial page. Replace placeholders with your custom content, including titles, introductions, images, sections, steps, and code examples.

```docc
@Tutorial(time: number) {
    @Intro(title: "Add the name of your title here.") {
        Add engaging introduction text here.
        
        @Image(source: intro-image-filename-here, alt: "Add an accessible description for your image here.")
    }
    
    @Section(title: "Add the name of your section here.") {
        @ContentAndMedia {
            Add engaging section text here.
            
            @Image(source: section-image-filename-here, alt: "Add an accessible description for your image here.")    
        }
        
        @Steps {
            @Step {
                Add engaging step 1 text here.

                @Image(source: step-1-image-filename-here, alt: "Add an accessible description for your step here.")
            }
            
            @Step {
                Add code for step 1 here.

                @Code(name: "code-display-name-here", file: "step-1-code-image-filename-here.jpg")
            }
        }
    }
}
```

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

### Discover Documentation Catalog and Create Bundle

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/InputDiscovery.md

Use `DocumentationContext.InputsProvider` to find a documentation catalog starting from a given point and then create a `DocumentationBundle` from its content. This is useful when your documentation is organized within a catalog.

```swift
let inputProvider = DocumentationContext.InputsProvider(fileManager: fileSystem)

guard let catalogURL = try inputProvider.findCatalog(startingPoint: startingPoint) else {
    return
}
let bundle = try inputProvider.makeInputs(contentOf: catalogURL, options: BundleDiscoveryOptions())

print("A bundle with ID: \(bundle.identifier)")
```

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

### Basic Swift Function

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/writing-symbol-documentation-in-your-source-files.md

An example of a Swift function without documentation comments.

```swift
// Eat the provided specialty sloth food.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
    ...
}
```

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

### Comprehensive Symbol Documentation Example

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/writing-symbol-documentation-in-your-source-files.md

Combine summary, detailed description, parameters, return values, and thrown errors in a single documentation comment for rich symbol documentation.

```swift
/// Eat the provided specialty sloth food.
///
/// Sloths love to eat while they move very slowly through their rainforest 
/// habitats. They're especially happy to consume leaves and twigs, which they 
/// digest over long periods of time, mostly while they sleep.
///
/// When they eat food, a sloth's `energyLevel` increases by the food's `energy`.
///
/// - Parameters:
///   - food: The food for the sloth to eat.
///   - quantity: The quantity of the food for the sloth to eat.
///
/// - Returns: The sloth's energy level after eating.
///
/// - Throws: `SlothError.tooMuchFood` if the quantity is more than 100.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
```

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

### Defining Steps in a Tutorial Section

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Steps/Steps.md

This snippet shows the structure for defining multiple steps within a tutorial section. Each step includes descriptive text and a code example with an associated image.

```swift
@Tutorial(time: 30) {
    
    ...
    
    @Section(title: "Create a Swift Package") {
        @ContentAndMedia {

            ...

        }
        
        @Steps {
            @Step {
                Create a new directory named `SwiftPackage`.
                
                @Code(name: "CreateDirectory.sh", file: 01-create-dir.sh) {
                    @Image(source: preview-01-create-directory.png, alt: "A screenshot from the command-line showing creating the directory using the `mkdir SwiftPackage` command.")
                }
            }

        @Step {
            Change into the new directory.
            
            @Code(name: "ChangeDirectory.sh", file: 02-change-directory.sh) {
                @Image(source: preview-02-change-directory.png, alt: "A screenshot from the command-line showing changing into the directory using the `cd SwiftPackage` command.")
            }
        }

            @Step {
                Create a new Swift Package.
                
                @Code(name: "Package.swift", file: 03-create-package.sh) {
                    @Image(source: preview-03-create-package.png, alt: "A screenshot from the command-line showing Swift Package creation using the `swift package init` command.")
                }
            }
            
            ...

        }
    }
}
```

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

### Project Directory Structure for Snippets

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

Illustrates the expected directory structure for a Swift package that includes a `Snippets` directory for code examples.

```text
YourProject
  ├── Package.swift
  ├── Snippets
  │   └── example-snippet.swift
  ├── Sources
  │   └── YourProject
  │       └── YourProject.swift
etc...
```

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

### Using the Stack Directive

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Stack.md

Demonstrates how to use the Stack directive within a Tutorial and Section to arrange multiple ContentAndMedia blocks horizontally. This example shows a basic structure for a multi-column layout.

```swift
@Tutorial(time: 30) {
    
    ...
    
    @Section(title: "Add a customization view") {
        @ContentAndMedia {
            Add the ability for users to customize sloths and select their powers.
            
            @Image(source: 01-creating-section2.png, alt: "An outline of a sloth surrounded by four power type icons. The power type icons are arranged in the following order, clockwise from the top: fire, wind, lightning, and ice.")
        }
        
        @Stack {
            @ContentAndMedia {
                ...
            }

            @ContentAndMedia {
                ...
            }

            @ContentAndMedia {
                ...
            }
        
        }
        ...
 
    }
}
```

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

### Intro Directive Example for Tutorials

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Shared Directives/Intro.md

Use the @Intro directive within a @Tutorials block to define the introduction for a table of contents page. Include a title, descriptive text, and an optional @Image or @Video.

```swift
@Tutorials(name: "SlothCreator") {
    @Intro(title: "Meet SlothCreator") {
        Create, catalog, and care for sloths using SlothCreator.
        Get started with SlothCreator by building the demo app _Slothy_.
        
        @Image(source: slothcreator-intro.png, alt: "An illustration of 3 iPhones in portrait mode, displaying the UI of finding, creating, and taking care of a sloth in Slothy — the sample app that you build in this collection of tutorials.")
    }
    
    ...
    
}

```

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

### Define a Custom Documentation Tool

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/DocCCommandLine/CommandLine.docc/CommandLine.md

Define a custom command-line tool that conforms to AsyncParsableCommand. This example shows how to configure abstract descriptions and include subcommands like ConvertAction and ExampleAction.

```swift
public import ArgumentParser

public struct MyDocumentationTool: AsyncParsableCommand {
    public static var configuration = CommandConfiguration(
        abstract: "My custom documentation tool",
        subcommands: [ConvertAction.self, ExampleAction.self]
    )
    
    public init() {
    }
}

MyDocumentationTool.main()

```

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

### Get DocC CLI Help

Source: https://github.com/swiftlang/swift-docc/blob/main/README.md

Run this command in your terminal to see instructions on how to use DocC from the command line interface.

```bash
docc --help
```

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

### Equivalent Aside Syntax Examples

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/other-formatting-options.md

Demonstrates equivalent syntax for single-line asides using Markdown list and block quote formats. These are interchangeable for short notes.

```markdown
- Note: Some information 
* Note: Some information 
+ Note: Some information 
> Note: Some information 
```

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

### Include GNUInstallDirs Module

Source: https://github.com/swiftlang/swift-docc/blob/main/CMakeLists.txt

Includes the GNUInstallDirs module, which provides standard installation directory variables.

```cmake
include(GNUInstallDirs)
```

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

### Get Source File URL for Documentation Node

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationContextGroup.md

Retrieve the URL of the source file for a given documentation node reference.

```swift
let sourceFileURL = try context.documentURL(for: reference)
```

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

### Define a Custom Benchmark Metric

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Benchmarking.md

Create a custom metric by adopting the `BenchmarkMetric` protocol. This example counts registered bundles in the `DocumentationContext`.

```swift
class BundlesCount: BenchmarkMetric {
  static let identifier = "bundles-count"
  static let displayName = "Bundles Count"
  
  var result: MetricValue?
  
  init(context: DocumentationContext) {
    result = .number(Double(context.registeredBundles.count))
  }
}
```

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

### Navigate to Swift Package Root

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Change the current directory to the root of your Swift package. This is the starting point for generating symbol graphs.

```bash
cd ~/Developer/swift-docc
```

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

### ContentAndMedia Directive Example

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Directives.md

Demonstrates the usage of the `@ContentAndMedia` directive, which requires enclosed content such as text or media directives like `@Image`.

```markdown
@ContentAndMedia {
    Add the `EmailValidator` code.
         
    @Image(source: code.png,
           alt: "EmailValidator(string: email.stringValue).validate()")
}
```

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

### Iterate Over Test Configurations

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Example of iterating over boolean configurations for testing. Consider using parameterized tests in Swift Testing for cleaner expression of such scenarios.

```swift
for withExplicitTechnologyRoot in [true, false] {
    for withPageColor in [true, false] {
       ...
```

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

### Document Method Parameters Using a Parameters Section

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/writing-symbol-documentation-in-your-source-files.md

Use a parameters section for documenting method parameters. Each parameter is a nested list item, starting with '- ' followed by the parameter name and its documentation.

```swift
/// - Parameters:
///   - food: The food for the sloth to eat.
///   - quantity: The quantity of the food for the sloth to eat.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
```

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

### Document Method Parameters Using Parameter Fields

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/writing-symbol-documentation-in-your-source-files.md

Use individual parameter fields for documenting method parameters. Each parameter is a top-level list item, starting with '- Parameter ' followed by the parameter name and its documentation.

```swift
/// - Parameter food: The food for the sloth to eat.
/// - Parameter quantity: The quantity of the food for the sloth to eat.
mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
```

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

### Example of ``Justification`` in a ``MultipleChoice`` Assessment

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Assessments/MultipleChoice/Choice/Justification.md

This snippet shows how to use the `Justification` directive within a `Choice` in a `MultipleChoice` assessment. The `reaction` parameter provides immediate feedback, and the following text explains why the answer is correct or incorrect.

```swift
@Tutorial(time: 30) {
        
    ...

    @Assessments {
        @MultipleChoice {
            What element did you use to add space around and between your views?
            
            @Choice(isCorrect: false) {
                A state variable.
                
                @Justification(reaction: "Try again!") {
                    Remember, it's something you used to arrange views vertically.
                }
            }
            
            ...
            
        }
    }
}
```

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

### Previewing an Interactive Tutorial

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/building-an-interactive-tutorial.md

Use this command to compile your tutorial and generate a preview. Copy the provided URL to view it in your browser.

```bash
docc preview MyPackage.docc --fallback-display-name MyPackage --fallback-bundle-identifier com.example.MyPackage --fallback-bundle-version 1
```

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

### Getting a Plain Text Representation

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/RenderingModel/RenderInlineContent.md

Provides a way to get a plain text representation of the inline content.

```APIDOC
## Getting a Plain Text Representation

### ``plainText``

A computed property that returns the plain text representation of the inline content.
```

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

### Tutorial Template

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Tutorial.md

Use this template to create a new tutorial file. Replace placeholders with your content.

```markdown
@Tutorial(time: <#number#>) {
    @Intro(title: "<#text#>") {
        <#text#>
        
        @Image(source: <#file#>, alt: "<#accessible description#>")
    }
    
    @Section(title: "<#text#>") {
        @ContentAndMedia {
            <#text#>
            
            @Image(source: <#file#>, alt: "<#accessible description#>")
        }
        
        @Steps {
            @Step {
                <#text#>
                @Image(source: <#file#>, alt: "<#accessible description#>")
            }
            
            @Step {
                <#text#>
                @Code(name: "<#display name#>", file: <#filename.swift#>)
            }
        }
    }
}
```

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

### DocC Disambiguation Suffix Examples

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md

This table shows examples of disambiguation suffixes DocC supports, including symbol type, parameter type names, return type names, and symbol identifier hashes.

```markdown
| Disambiguation type             | Example         | Meaning
| ------------------------------- | --------------- | ------------
| Type of symbol                  | `-enum`         | This symbol is an enumeration.
| Parameter type names            | `-(Int,_,_)`    | This symbol has three parameters and the first parameter is an `Int` value.
| ^                               | `-()`           | This symbol has no parameters.
| Return type names               | `->String`      | This symbol returns a `String` value.
| ^                               | `->(_,_)`       | This symbol returns a tuple with two elements.
| Parameter and return type names | `-(Bool)->()`   | This symbol has one `Bool` parameter and no return value.
| Symbol identifier hash          | `-4gcpg`        | The hash of this symbol's unique identifier is "`4gcpg`".
```

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

### MyClass Availability

Source: https://github.com/swiftlang/swift-docc/blob/main/Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/MyClass.md

MyClass is available starting from iOS 16.0.

```APIDOC
## MyClass

@Metadata {
    @Available(iOS, introduced: "16.0")
}

<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
```

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

### Tutorial Structure with Steps

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/Steps/Step/Step.md

Illustrates the hierarchical structure of a tutorial, including an intro, sections with content, and a set of steps.

```swift
@Tutorial(time: 30) {
    @Intro(title: "Creating Custom Sloths") {
        
        ... 

    }
    
    @Section(title: "Create a new folder and add SlothCreator") {
        @ContentAndMedia {
            
            ... 
            
        }
        
        @Steps {
            @Step {
                Create the folder.
                
                @Image(source: placeholder-image, alt: "A screenshot using the `mkdir` command to create a folder to place SlothCreator in.")
            }
            
            ...
                            
        }
    }
}
```

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

### Add Tutorial Introduction

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Tutorial.md

Define the introduction section of a tutorial page using the `Intro` directive. Include a title, descriptive text, and an optional image.

```markdown
@Tutorial(time: 30) {
    @Intro(title: "Creating and Building a Swift Package") {
        This tutorial guides you through creating and building a Swift Package. Use the package to add your own re-usable classes and structures.
        
        @Image(source: creating-intro, alt: "An image of the Swift logo.")
    }

    ...
    
}
```

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

### Get Artist

Source: https://github.com/swiftlang/swift-docc/blob/main/Tests/SwiftDocCTests/Test Bundles/HTTPRequests.docc/GetArtist.md

Retrieves artist information based on the provided ID and optional limit.

```APIDOC
## GET /artists/{id}

### Description
Get Artist request. The endpoint discussion.

### Method
GET

### Endpoint
/artists/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - ID docs.

#### Query Parameters
- **limit** (integer) - Optional - Limit query parameter.

#### Request Body
- **ignored** (any) - Optional - Ignored parameter.

### Request Example
```json
{
  "example": "Simple body."
}
```

### Response
#### Success Response (200)
- **json** (object) - Everything is good with json.

#### Success Response (204)
- **content** (null) - Success without content.

#### Error Response (887)
- **value** (string) - Bad value.

#### Response Example
```json
{
  "example": "response body"
}
```
```

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

### Provide Downloadable Project Files

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Tutorial.md

Include downloadable resources for your tutorial by specifying the archive's name and extension in the `projectFiles` parameter.

```markdown
@Tutorial(time: 30, projectFiles: "SlothCreatorFiles.zip") {

    ...

}
```

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

### Tutorial Structure with Resources

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorials/Tutorials.md

Includes a dedicated section for related resources, such as videos and downloads, using the `Resources` directive. This provides readers with additional learning materials and links.

```markdown
@Tutorials(name: "SlothCreator") {
    @Intro(title: "Meet SlothCreator") {
        
        ...
    }
    
    @Chapter(name: "SlothCreator Essentials") {
        ...
    }
    
    @Chapter(name: "Basic Sloth Care") {
        ...
    }
    
    @Chapter(name: "Basic Sloth Interaction") {
        ...
    }

    @Resources {
        Explore more resources for learning about sloths.

        @Videos(destination: "https://www.example.com/sloth-videos/") {
            Watch cute videos of sloths climbing, eating, and sleeping.

            - [Treetop Breakfast](https://www.example.com/sloth-videos/breakfast/)
            - [Slow Ascent](https://www.example.com/sloth-videos/climb/)
            - [Rest Time](https://www.example.com/sloth-videos/snoozing/)
        }

        @Downloads(destination: "https://www.example.com/images/sloth-wallpaper/") {
            Download the cutest sloth wallpaper for your iPhone, iPad, or Mac.
        }

    }
}
```

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

### Define Tutorial Structure with Sections and Steps

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Tutorial.md

Use the `@Tutorial`, `@Section`, `@ContentAndMedia`, and `@Steps` directives to organize tutorial content. Include `@Step` directives for individual tasks.

```swift
@Tutorial(time: 30) {
    @Intro(title: "Creating Custom Sloths") {
        
        ... 

    }
    
    @Section(title: "Create a Swift Package in a new directory") {
        @ContentAndMedia {
            
            ... 
            
        }
        
        @Steps {
            @Step {
                Create the directory.
                
                @Image(source: placeholder-image, alt: "A screenshot showing the command to type in the terminal to create the directory.")
            }
            
            @Step {
                Create the Swift Package. 
                
                @Image(source: placeholder-image, alt: "A screenshot showing the command to type in the terminal to create the Swift package.")
            }
            
            @Step {

                ... 

            }
            
            @Step {

                ... 

            }
        }
    }
    
    @Section(title: "Add a customization view") {
        @ContentAndMedia {

            ... 

        }
        
        @Steps {
        
            ... 

        }
    }
}
```

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

### Preview Generated Bundle

Source: https://github.com/swiftlang/swift-docc/blob/main/bin/make-test-bundle/README.md

After generating the test bundle, use this command to preview the documentation locally.

```bash
docc preview path/to/folder/TestFramework/Docs.docc
```

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

### Create a Documentation Context

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/DocumentationContextGroup.md

Use this to create a context for a given bundle. Requires inputs provider, bundle discovery options, and a catalog URL.

```swift
let inputsProvider = DocumentationContext.InputsProvider()
let (bundle, dataProvider) = try inputsProvider.inputsAndDataProvider(
    startingPoint: catalogURL, 
    options: bundleDiscoveryOptions
)

let context = try DocumentationContext(bundle: bundle, dataProvider: dataProvider)
```

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

### Link to a Tutorial

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/linking-to-symbols-and-other-content.md

Link to a tutorial using the `<doc:TutorialName>` syntax. If an article and tutorial share a base name, prefix the link with `tutorials/` or `/tutorials/` to specifically target the tutorial.

```markdown
<doc:SlothCreator>
```

```markdown
<doc:tutorials/BaseName>
```

```markdown
<doc:/tutorials/BaseName>
```

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

### Snippet in Tab Navigator

Source: https://github.com/swiftlang/swift-docc/blob/main/Tests/SwiftDocCTests/Test Bundles/Snippets.docc/Snippets.md

Embed a snippet slice within a tabbed navigation structure. This example shows a snippet slice within the second tab.

```swift
@Snippet(path: "Snippets/Snippets/MySnippet", slice: "middle") {}
```

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

### Basic Tutorial Structure

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorials/Tutorials.md

Defines the basic structure of a tutorial with an introduction and a chapter. Use the `name` parameter for the tutorial's overall name. The `Intro` directive provides introductory text and an image, while `Chapter` directives link to individual tutorial pages.

```markdown
@Tutorials(name: "SlothCreator") {
    @Intro(title: "Meet SlothCreator") {
        Create, catalog, and care for sloths using SlothCreator. 
        Get started with SlothCreator by building the demo app _Slothy_.
        
        @Image(source: slothcreator-intro, alt: "An illustration of 3 iPhones in portrait mode, displaying the UI of finding, creating, and taking care of a sloth in Slothy — the sample app that you build in this collection of tutorials.")
    }
    
    @Chapter(name: "SlothCreator Essentials") {
        @Image(source: chapter1-slothcreatorEssentials, alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
        
        Create custom sloths and edit their attributes and powers using SlothCreator.
        
        @TutorialReference(tutorial: "doc:Creating-Custom-Sloths")
    }
}
```

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

### Enable/Disable Feature Flags

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md

Control experimental UI features using the 'features' section in `theme-settings.json`. For example, set 'features.docs.onThisPageNavigator.disable' to `true` to disable the on-page navigation.

```json
{
  "features": {
    "docs": {
      "quickNavigation": {
        "enable": true
      }, 
      "onThisPageNavigator": {
        "disable": true
      }
    }
  }
}
```

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

### Tutorial DocC Project Structure

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/DocCCommandLine/CommandLine.docc/CommandLine/Actions/InitAction.md

Illustrates the file structure for a DocC project using the tutorial template.

```text
⎯ Tutorial.docc
    ├ table-of-contents.tutorial
    ├ Chapter01
    ⎜   ├ page-01.tutorial
    ⎜   ⎣ Resources
    ⎣ Resources
```

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

### Using ContentAndMedia in a Tutorial Section

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Section/ContentAndMedia.md

Demonstrates how to embed text and an image within a ContentAndMedia directive inside a tutorial's Section. This is useful for explaining concepts visually.

```swift
@Tutorial(time: 30) {
    
    ...
    
    @Section(title: "Add a customization view") {
        @ContentAndMedia {
            Add the ability for users to customize sloths and select their powers.
            
            @Image(source: 01-creating-section2.png, alt: "An outline of a sloth surrounded by four power type icons. The power type icons are arranged in the following order, clockwise from the top: fire, wind, lightning, and ice.")
        }
            
        ...
 
    }
}
```

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

### Build Documentation Archive with Hosting Base Path

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/distributing-documentation-to-other-developers.md

Use the `docc convert` command with `--hosting-base-path` to specify a custom subpath for your documentation archive.

```shell
docc convert MyNewPackage.docc \
  --additional-symbol-graph-dir .build \
  --output-dir MyNewPackage.doccarchive \
  --hosting-base-path MyProject/Base/Path
```

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

### Defining a Multiple Choice Question with Choices

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Assessments/MultipleChoice/Choice/Choice.md

Example of how to structure a multiple-choice question within a tutorial's assessment section, including incorrect and correct choices with justifications.

```swift
@Tutorial(time: 30) {
    
    ... 

    @Assessments {
        @MultipleChoice {
            What element did you use to add space around and between your views?

            @Choice(isCorrect: false) {
                A state variable.

                @Justification(reaction: "Try again!") {
                    Remember, it's something you used to arrange views vertically.
                }
            }

            ...
           
        }
    }
}
```

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

### Multi-paragraph Aside with List Syntax

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/other-formatting-options.md

Shows how to format multi-paragraph asides using Markdown's list syntax. Indent subsequent paragraphs to align with the start of the aside content.

```markdown
- Note: The first paragraph. 
 
  The second paragraph.
```

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

### Preview Documentation with Snippets

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

Preview your documentation, including code snippets, using the `swift-docc-plugin`. Replace `YourTarget` with a target from your package.

```bash
swift package --disable-sandbox preview-documentation --target YourTarget
```

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

### Define Advanced Color Variations

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md

This example shows how to define specialized dark and light versions for background and navigation colors using HSL color values based on a defined hue.

```json
{
  "theme": {
    "color": {
      "hue-green": "120",
      "fill": {
        "dark": "hsl(var(--color-hue-green), 100%, 10%)",
        "light": "hsl(var(--color-hue-green), 100%, 90%)"
      },
      "fill-secondary": {
        "dark": "hsl(var(--color-hue-green), 100%, 20%)",
        "light": "hsl(var(--color-hue-green), 100%, 80%)"
      },
      "nav-solid-background": "var(--color-fill)"
    }
  }
}
```

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

### Adding a Resources Section to a Tutorial

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorials/Resources/Resources.md

Use the `@Resources` directive within a `@Tutorials` block to add a section with links to related materials. Include introductory text and then specific resource directives like `@Videos` and `@Downloads`.

```swift
@Tutorials(name: "SlothCreator") {
    
    ...
    
    @Resources {
        Explore more resources for learning about sloths.

        @Videos(destination: "https://www.example.com/sloth-videos/") {
            Watch cute videos of sloths climbing, eating, and sleeping.

            - [Treetop Breakfast](https://www.example.com/sloth-videos/breakfast/)
            - [Slow Ascent](https://www.example.com/sloth-videos/climb/)
            - [Rest Time](https://www.example.com/sloth-videos/snoozing/)
        }

        @Downloads(destination: "https://www.example.com/images/sloth-wallpaper/") {
            Download the cutest sloth wallpaper for your iPhone, iPad, or Mac.
        }
    }
}
```

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

### Table of Contents Tutorial Structure

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/building-an-interactive-tutorial.md

Use this structure to create a table of contents file for your tutorial. It defines the tutorial's name, introduction, and chapters, referencing individual tutorial pages.

```swift
@Tutorials(name: "Add the name of your tutorial here. This usually matches your framework name.") {
    @Intro(title: "Add a title for your introduction here.") {
        Add engaging introduction text here.
        
        @Image(source: toc-introduction-image-filename, alt: "Add an accessible description for your image here.")
    }
    
    @Chapter(name: "Add a chapter title here.") {
        Add chapter text here.
        
        @Image(source: chapter-image-filename-here, alt: "Add an accessible description for your image here.")
        
        @TutorialReference(tutorial: "doc:tutorial-page-file-name-here")
        @TutorialReference(tutorial: "doc:another-tutorial-page-file-name-here")
    }

    @Chapter(name: "Add the next chapter title here.") {
    }
}
```

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

### Markdown Article Structure

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-supplemental-content-to-a-documentation-catalog.md

An example of the basic structure for a DocC article, including a title, abstract, and overview section. The first level 1 header is regular content, not a symbol reference.

```markdown
# Getting Started with Sloths

Create a sloth and assign personality traits and abilities.

## Overview

Sloths are complex creatures that require careful creation and a suitable
habitat.
...
```

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

### Build Swift-DocC

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Compile the Swift-DocC project from the command line.

```bash
swift build
```

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

### Add Tutorial Link to Chapter

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Shared Directives/Chapter/TutorialReference.md

Use the TutorialReference directive within a chapter to link to a tutorial page. The 'tutorial' parameter must be the page's filename prefixed with 'doc:'.

```swift
@Tutorials(name: "SlothCreator") {
    
    ...    
    
    @Chapter(name: "SlothCreator Essentials") {
        @Image(source: chapter1-slothcreatorEssentials.png, alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
        
        Create custom sloths and edit their attributes and powers using SlothCreator.
        
        @TutorialReference(tutorial: "doc:Creating-Custom-Sloths")
    }

    ...
    
}

```

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

### Create Virtual File System for Test Inputs

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Use virtual file systems with `load(catalog:...)`, `makeSymbolGraph(...)`, and `makeSymbol(...)` to define test inputs for symbol documentation and extension files.

```swift
let catalog = Folder(name: "Something.docc", content: [
    JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
        makeSymbol(id: "some-symbol-id", kind: .class, pathComponents: ["SomeClass"], docComment: """
        This is the in-source documentation for this class.    
        """)
    ])),
    
    TextFile(name: "Something.md", utf8Content: """# ``SomeClass``

This is additional documentation for this class
"""),
])
let context = try await load(catalog: catalog)
// Test rest of your test
```

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

### Aside with First Paragraph on New Line (List Syntax)

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/other-formatting-options.md

An alternative multi-paragraph aside format using list syntax where the first paragraph starts on a new line after the aside tag.

```markdown
- Note: 
  The first paragraph. 
 
  The second paragraph.
```

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

### Configure Apache for Documentation Hosting

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/distributing-documentation-to-other-developers.md

Use an `.htaccess` file to configure Apache's `mod_rewrite` for routing documentation and tutorial pages, as well as supporting bundled assets.

```apache
# Enable custom routing.
RewriteEngine On

# Route documentation and tutorial pages.
RewriteRule ^(documentation|tutorials)\/.*$ MyNewPackage.doccarchive/index.html [L]

# Route files and data for the documentation archive.
#
# If the file path doesn't exist in the website's root ...
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# ... route the request to that file path with the documentation archive.
RewriteRule .* MyNewPackage.doccarchive/$0 [L]
```

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

### Define a Chapter with Tutorials

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Shared Directives/Chapter/Chapter.md

Use the @Chapter directive within a @Tutorials block to group related tutorial pages. Specify the chapter name using the `name` parameter and include an optional @Image and descriptive text. Each chapter must contain at least one @TutorialReference.

```swift
@Tutorials(name: "SlothCreator") {
    
    ...
    
    @Chapter(name: "SlothCreator Essentials") {
        @Image(source: chapter1-slothcreatorEssentials, alt: "A wireframe of an app interface that has an outline of a sloth and four buttons below the sloth. The buttons display the following symbols, from left to right: snowflake, fire, wind, and lightning.")
        
        Create custom sloths and edit their attributes and powers using SlothCreator.
        
        @TutorialReference(tutorial: "doc:Creating-Custom-Sloths")
    }

    ...
    
}
```

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

### Convert Package to Documentation Archive

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/distributing-documentation-to-other-developers.md

Use the `docc convert` command to create a documentation archive for a Swift package. Specify fallback information and an output directory.

```shell
docc convert MyNewPackage.docc \
  --fallback-display-name MyNewPackage \
  --fallback-bundle-identifier com.example.MyNewPackage \
  --fallback-bundle-version 1 \
  --additional-symbol-graph-dir .build \
  --output-dir MyNewPackage.doccarchive
```

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

### Create Bundle from Symbol Graph Files

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/InputDiscovery.md

Create a `DocumentationBundle` and its associated `DataProvider` directly from a list of symbol graph files. This is useful when you have symbol graphs but no explicit documentation catalog.

```swift
let inputProvider = DocumentationContext.InputsProvider(fileManager: fileSystem)

guard let (bundle, dataProvider) = try inputProvider.makeInputsFromSymbolGraphs(
    options: BundleDiscoveryOptions(
        additionalSymbolGraphFiles: listOfSymbolGraphLocations
    )
) else {
    return
}

print("A bundle with ID: \(bundle.identifier)")
```

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

### Hide and Show Snippet Segments

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

Use `// snippet.hide` and `// snippet.show` comments to control which parts of a code snippet are displayed in your documentation. This is useful for excluding setup code or license footers.

```swift
print("Hello")

// snippet.hide

print("Hidden")

// snippet.show

print("Shown")
```

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

### init()

Source: https://github.com/swiftlang/swift-docc/blob/main/Tests/SwiftDocCTests/Test Bundles/BundleWithLonelyDeprecationDirective.docc/CoolClass.init.md

This is the deprecated initializer for CoolClass. Use `init(config:cache:)` instead.

```APIDOC
## init()

### Description
Aw yeah, we're overriding things.

### Deprecation Summary
Use the ``CoolClass/init(config:cache:)`` initializer instead.
```

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

### Aside with First Paragraph on New Line (Block Quote Syntax)

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/other-formatting-options.md

An alternative multi-paragraph aside format using block quote syntax where the first paragraph starts on a new line after the aside tag.

```markdown
> Note: 
> The first paragraph. 
> 
> The second paragraph.
```

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

### Estimate Tutorial Completion Time

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorial/Tutorial.md

Provide an estimated completion time in minutes using the `time` parameter to help readers gauge the tutorial's length.

```markdown
@Tutorial(time: 30) {

    ...

}
```

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

### Multi-paragraph Aside with Block Quote Syntax

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/other-formatting-options.md

Illustrates multi-paragraph asides using Markdown's block quote syntax. Each line, including blank lines between paragraphs, must start with a greater-than sign (>).

```markdown
> Note: The first paragraph. 
> 
> The second paragraph.
```

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

### Basic Downloads Directive

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorials/Resources/Downloads.md

Use the Downloads directive to add a single 'View downloads' link to the resources section of a tutorial. The destination parameter specifies the URL for this link.

```swift
@Tutorials(name: "SlothCreator") {
    
    ...
    
    @Resources {
        Explore more resources for learning about sloths.

        @Downloads(destination: "https://www.example.com/sloth-downloads/") {
            Download resources that make sloth development even more fun.
        }

    }

}
```

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

### Define and End Code Snippet Slices

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

Annotate non-overlapping slices within a snippet using `// snippet.<slice-id>` to start a slice and `// snippet.end` to terminate it. Adding a new slice identifier automatically ends the previous one.

```swift
// snippet.setup
var item = MyObject.init()
// snippet.end

// snippet.configure
item.size = 3
// snippet.end
```

```swift
// snippet.setup
var item = MyObject.init()

// snippet.configure
item.size = 3
```

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

### Navigate to Repository Directory

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Change your current directory to the root of the cloned Swift-DocC repository.

```bash
cd swift-docc
```

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

### Add a Documentation Extension Page Title

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

For documentation extension files, use a page title that includes a symbol link by wrapping the path to the symbol in double backticks (`). The path can start with the framework's module name or a top-level symbol name.

```markdown
# ``SlothCreator/CareSchedule/Event``
```

```markdown
# ``CareSchedule/Event``
```

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

### Generate Test Bundle

Source: https://github.com/swiftlang/swift-docc/blob/main/bin/make-test-bundle/README.md

Use this command to generate a Swift framework for DocC testing. Specify the output directory and the size factor for the generated nodes.

```bash
swift run make-test-bundle --output path/to/folder --sizeFactor 10
```

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

### Tutorial Template - Chapter Page

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/DocCCommandLine/CommandLine.docc/CommandLine/Actions/InitAction.md

Defines the structure for a single page within a DocC tutorial. It includes an introduction, sections with content, media, and steps.

```tutorial
@Tutorial() {
    @Intro(title: "Tutorial Page Title") {
        Add one paragraph that introduce your tutorial.
    }
    @Section(title: "Section Name") {
        @ContentAndMedia {
            Add text that introduces the tasks that the reader needs to follow.
            @Image(source: "add-your-section-image-filename-here.jpg", alt: "Add an accessible description for your image here.")
        }
        @Steps {
            @Step {
                This is a step with code.
                @Code(name: "", file: "")
            }
            @Step {
                This is a step with an image.
                @Image(source: "", alt: "")
            }
        }
    }
}
```

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

### Basic Video Directive

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Shared Directives/Video.md

Use the `@Video` directive to embed a video in your tutorial. Specify the source video file and a poster image. The system automatically selects the appropriate poster image variant based on the reader's display and appearance settings.

```swift
@Video(source: "sloth-smiling.mp4", poster: "happy-sloth-frame.png")
```

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

### Add Framework Overview to Landing Page

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/adding-structure-to-your-documentation-pages.md

After the H1 heading and a blank line, provide a single sentence for the page's abstract, followed by another blank line and the Overview section.

```markdown
# ``SlothCreator``

Catalog sloths you find in nature and create new adorable virtual sloths.
```

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

### MyClass Constructors and Methods

Source: https://github.com/swiftlang/swift-docc/blob/main/Tests/SwiftDocCTests/Test Bundles/LegacyBundle_DoNotUseInNewTests.docc/documentation/myclass.md

This section details the available constructors and methods for MyClass.

```APIDOC
## MyClass

MyClass abstract.

### Initializers

- `init()`
- `init()`

### Methods

- `myFunction()`
```

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

### Create a Numbered List

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

Precede each item with its step number, a period, and a space to create a numbered list. This is useful for sequential instructions.

```markdown
1. Give the sloth some food.
2. Take the sloth for a walk.
3. Read the sloth a story.
4. Put the sloth to bed.
```

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

### Run Swift-DocC CLI

Source: https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md

Execute the built Swift-DocC command-line interface.

```bash
swift run docc
```

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

### Configure BitBucket Source Linking

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/distributing-documentation-to-other-developers.md

Enable automatic linking to your project's sources on BitBucket by providing the source service, base URL, and local checkout path.

```bash
docc convert […] \
    --source-service bitbucket \
    --source-service-base-url https://bitbucket.org/<org>/<repo>/src/<branch> \
    --checkout-path <absolute path to local checkout>
```

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

### Add Sample Code Links with @SampleCode

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/Reference Syntax/Tutorials Syntax/Top-Level Directives/Tutorials/Resources/SampleCode.md

Use the @SampleCode directive within @Resources to link to external sample code projects. The `destination` parameter provides a general link, while the body of the directive can contain descriptive text and specific Markdown links to individual code pages.

```swift
@Tutorials(name: "SlothCreator") {
    
    ...
    
    @Resources {
        Explore more resources for learning about sloths.

        @SampleCode(destination: "https://www.example.com/sloth-code/") {
            Download and explore sample code projects to get to know SlothCreator.

            - [SlothyRoad: Building a Fun, Yet Slow Game](https://www.example.com/sloth-code/slothyroad/)
            - [SpeedySloth: Designing a Faster, More Powerful Sloth](https://www.example.com/sloth-code/speedy/)
            - [SmoothSloth: Adding a Smooth and Glossy Coat to Your Sloth](https://www.example.com/sloth-code/smooth/)
        }
    }
}
```

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

### Create a Swift Code Listing

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

Use three backticks followed by the language name (e.g., `swift`) to create a code listing. Terminate the listing with another three backticks. Use spaces for indentation.

```swift
struct Sightseeing: Activity {
    func perform(with sloth: inout Sloth) -> Speed {
        sloth.energyLevel -= 10
        return .slow
    }
}
```

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

### Add an Overview Section Header

Source: https://github.com/swiftlang/swift-docc/blob/main/Sources/docc/DocCDocumentation.docc/formatting-your-documentation-content.md

Use a double hash (##) followed by a space to create an 'Overview' or 'Discussion' section header.

```markdown
## Overview
```
Tokens:
Raw