docs: Update titles and headings to be more consistent (#394)

Author: parlough

third_party/docsite/src/components/docs/TableofContents.astro

@@ -13,7 +13,7 @@ const { class: className } = Astro.props;
 {
   hasToC && (
     <div class:list={["relative", className]}>
-      <h2 class="text-xl border-none">On This Page</h2>
+      <h2 class="text-xl border-none">On this page</h2>
       <ul class="list-none m-0">
         {toc.map((heading) => (
           <li class=`${heading.depth === 2 ? "font-semibold" : "text-muted-foreground"}${heading.depth > 3 ? " pl-4" : ""}`>

third_party/docsite/src/content/docs/getting-started.mdx

@@ -1,5 +1,5 @@
 ---
-title: Getting Started
+title: Get started
 hide_breadcrumbs: true
 ---
 import Callout from "@/components/Callout.astro";
@@ -24,9 +24,9 @@ An executable prompt template is a file that contains not only the text of a pro
 
 This combination of features makes it possible to treat a Dotprompt file as an executable unit, streamlining the process of working with AI models and ensuring consistency across different uses of the same prompt.
 
-## Example `.prompt` file
+## Example file
 
-Here's an example of a Dotprompt file that extracts structured data from provided text:
+Here's an example of a Dotprompt file that extracts structured data from the provided text:
 
 ```handlebars
 ---
@@ -39,7 +39,7 @@ output:
   schema:
     title?: string, the title of the article if it has one
     summary: string, a 3-sentence summary of the text
-    tags?(array, a list of string tag category for the text): string, 
+    tags?(array, a list of string tag category for the text): string,
 ---
 
 Extract the requested information from the given text. If a piece of information is not present, omit that field from the output.
@@ -57,7 +57,7 @@ This Dotprompt file:
 
 When executed, this prompt would take a text input, analyze it using the specified AI model, and return a structured JSON object with the extracted information.
 
-## Installation
+## Install and set up
 
 The remainder of this getting started guide will use the reference Dotprompt implementation included as part of the [Firebase Genkit](https://github.com/firebase/genkit) GenAI framework. To use other implementations of Dotprompt, see the [list of Implementations](/implementations).
 

third_party/docsite/src/content/docs/implementors.mdx

@@ -10,4 +10,4 @@ Implementing the Dotprompt spec consists of two primary areas of work:
 
 ## 🚧 Under Construction 🚧
 
-This page is under construction, check back soon!
+This page is under construction, check back soon!

third_party/docsite/src/content/docs/reference.mdx

@@ -1,5 +1,5 @@
 ---
-title: Reference Docs
+title: Reference docs
 ---
 
 A Dotprompt template format is made up of four parts:
@@ -15,9 +15,9 @@ output:
 {{! (3) the Template Content goes here }}
 ```
 
-When executed, a Dotprompt template renders into (4) Common Model Interface. 
+When executed, a Dotprompt template renders into (4) Common Model Interface.
 
-## Reference Docs
+## Reference docs
 
 1. **[Prompt Frontmatter](/reference/frontmatter):** Included at the start of a Dotprompt template, frontmatter includes model configuration, input/output formatList, and tooling MediaMetadata.
 2. **[Picoschema](/reference/picoschema):** The compact, YAML-optimized schema representation used for describing structured data in a Dotprompt template.

third_party/docsite/src/content/docs/reference/frontmatter.mdx

@@ -1,5 +1,5 @@
 ---
-title: Prompt Frontmatter
+title: Prompt frontmatter
 sort_order: 1
 ---
 
@@ -17,7 +17,7 @@ Prompt template goes here.
 
 All frontmatter fields are considered optional in a given `.prompt` file, as Dotprompt implementations may provide default values for any or all of them. If no frontmatter fields need to be specified in a given file, the frontmatter may be omitted entirely and only a prompt template provided.
 
-## Full Example
+## Full example
 
 Here's an example of a Dotprompt frontmatter:
 
@@ -26,7 +26,7 @@ Here's an example of a Dotprompt frontmatter:
 name: greetingPrompt
 variant: formal
 model: googleai/gemini-1.5-flash
-tools: 
+tools:
   - timeOfDay
 config:
   version: gemini-1.5-flash-latest
@@ -52,25 +52,30 @@ metadata:
 ---
 ```
 
-## Available Fields
+## Available fields
 
 ### `name`
+
 - **Type:** `string`
 - **Description:** The name of the prompt. If unspecified, inferred by the filename of the loaded prompt (e.g. `myPrompt.prompt` has an inferred name of `myPrompt`).
 
 ### `variant`
+
 - **Type:** `string`
 - **Description:** The variant name for the prompt. If unspecified, inferred by the filename of the loaded prompt (e.g. `myPrompt.variant1.prompt` has inferred name of `myPrompt` and inferred variant of `variant1`).
 
 ### `model`
+
 - **Type:** `string` or `ModelArgument<Options>`
 - **Description:** The name of the model to use for this prompt, e.g., `googleai/gemini-1.5-flash-latest`. The Dotprompt implementation is responsible for resolving a string model name to an executable model.
 
 ### `tools`
+
 - **Type:** `string[]`
 - **Description:** Names of tools (registered in the Dotprompt implementation) to allow use of in this prompt.
 
 ### `config`
+
 - **Type:** `object`
 - **Description:** Configuration to be passed to the model implementation as a `Map<string,any>`. The specific configuration options vary depending on the model implementation.
 - **Common Config:** Model implementations should respect the following config properties where applicable:
@@ -107,6 +112,7 @@ metadata:
     - **Example:**  `["END", "\n\n", "User:"]`
 
 ### `input`
+
 - **Type:** `object`
 - **Description:** Defines the input variables the prompt. If `input` is not specified, the implementation should accept any `Map<string,any>` values as input and pass them to the prompt template.
 - **Properties:**
@@ -118,22 +124,24 @@ metadata:
     - **Description:** Schema representing the input values for the prompt. Must correspond to a JSON Schema `object` type.
 
 ### `output`
+
 - **Type:** `object`
 - **Description:** Defines the expected model output format.
 - **Properties:**
   - `format`:
     - **Type:** `string`
     - **Common Values:** `json`, `text`
-    - **Description:** Desired output format for this prompt. Output formats are implementation-specific, but 
+    - **Description:** Desired output format for this prompt. Output formats are implementation-specific, but
   - `schema`:
     - **Type:** [Schema](schema)
     - **Description:** Schema representing the expected output from the prompt. Must correspond to a JSON Schema `object` type.
 
 ### `metadata`
+
 - **Type:** `Map<string, any>`
 - **Description:** Arbitrary metadata to be used by code, tools, and libraries.
 
-## Frontmatter Extensions
+## Frontmatter extensions
 
 In the frontmatter, Dotprompt implementations will automatically collect namespaced fields (i.e. fields with a `.` in them) into a special `ext` property on the resulting metadata. For example, the following frontmatter:
 
@@ -169,4 +177,4 @@ Would be parsed into this equivalent metadata:
 }
 ```
 
-Note that nested namespaces are flattened into dotted keys to avoid conflicts between nested properties and nested namespaces.
+Note that nested namespaces are flattened into dotted keys to avoid conflicts between nested properties and nested namespaces.

third_party/docsite/src/content/docs/reference/model.mdx

@@ -7,9 +7,9 @@ Dotprompt implementations are not required to conform to any specific structured
 
 In the future, a Dotprompt "spec test" will be made available that exercises the various parts of Dotprompt and compares the results to this common model request format.
 
-## GenerateRequest
+## `GenerateRequest`
 
-### Full Example
+### Full example
 
 ```json
 {
@@ -113,132 +113,159 @@ In the future, a Dotprompt "spec test" will be made available that exercises the
   ]
 }
 ```
+
 ### Properties
 
 #### `messages`
+
 - **Type:** `array` of [Message](#message) objects.
 - **Description:** The conversation history and current prompt.
 
 #### `config`
+
 - **Type:** [ModelConfig](#modelconfig)
 - **Description:** Configuration options for the model.
 
 #### `tools`
+
 - **Type:** `array` of [ToolDefinition](#tooldefinition)
 - **Description:** Definitions of tools available to the model.
 
 #### `output`
+
 - **Type:** [Output](#output)
 - **Description:** Specification for the desired output format.
 
 #### `context`
+
 - **Type:** `array` of [Document](#document)
 - **Description:** Grounding context documents for the model.
 
-## Message
+## `Message`
 
 A message represents a single "turn" in a multi-turn conversation. Each message must have a role and specified content.
 
 ### Properties
 
 #### `role`
+
 - **Type:** `string`
 - **Description:** The role of the message sender. Can be "system", "user", "model", or "tool".
 
 #### `content`
+
 - **Type:** `array` of [Part](#part)
 - **Description:** The content of the message, which can include text, media, tool requests, and tool responses.
 
 #### `metadata`
+
 - **Type:** `object`
 - **Description:** Optional. Additional metadata for the message.
 
-## Part
+## `Part`
 
 A `Part` object can be one of the following types:
 
-### TextPart
+### `TextPart`
 
 #### `text`
+
 - **Type:** `string`
 - **Description:** The text content of the message.
 
-### MediaPart
+### `MediaPart`
 
 #### `media`
+
 - **Type:** `object`
 - **Description:** Contains media information.
 
 #### `media.contentType`
+
 - **Type:** `string`
 - **Description:** Optional. The media content type. Inferred from data URI if not provided.
 
 #### `media.url`
+
 - **Type:** `string`
 - **Description:** A `data:` or `https:` URI containing the media content.
 
-### ToolRequestPart
+### `ToolRequestPart`
 
 #### `toolRequest`
+
 - **Type:** `object`
 - **Description:** A request for a tool to be executed.
 
 #### `toolRequest.ref`
+
 - **Type:** `string`
 - **Description:** Optional. The call ID or reference for a specific request.
 
 #### `toolRequest.name`
+
 - **Type:** `string`
 - **Description:** The name of the tool to call.
 
 #### `toolRequest.input`
+
 - **Type:** `any`
 - **Description:** Optional. The input parameters for the tool, usually a JSON object.
 
-### ToolResponsePart
+### `ToolResponsePart`
 
 #### `toolResponse`
+
 - **Type:** `object`
 - **Description:** A provided response to a tool call.
 
 #### `toolResponse.ref`
+
 - **Type:** `string`
 - **Description:** Optional. The call ID or reference for a specific request.
 
 #### `toolResponse.name`
+
 - **Type:** `string`
 - **Description:** The name of the tool.
 
 #### `toolResponse.output`
+
 - **Type:** `any`
 - **Description:** Optional. The output data returned from the tool, usually a JSON object.
 
-## ModelConfig
+## `ModelConfig`
 
 `ModelConfig` is an arbitrary `Map<string,any>` that depends on the specific implementation of the underlying model. However, the following common configuration options should be respected in implementation whenever applicable:
 
-### Common Config Properties
+### Common config properties
+
 #### `temperature`
+
 - **Type:** `number`
 - **Description:** Optional. Controls the randomness of the model's output.
 
 #### `maxOutputTokens`
+
 - **Type:** `number`
 - **Description:** Optional. Limits the maximum number of tokens in the model's response.
 
 #### `topK`
+
 - **Type:** `number`
 - **Description:** Optional. Limits the number of highest probability vocabulary tokens to consider at each step.
 
 #### `topP`
+
 - **Type:** `number`
 - **Description:** Optional. Sets a probability threshold for token selection.
 
 #### `stopSequences`
+
 - **Type:** `array` of `string`
 - **Description:** Optional. Sequences that, if encountered, will cause the model to stop generating further output.
 
-## Tool Object
+## `Tool` object
 
 ### `name`
 - **Type:** `string`
@@ -256,27 +283,32 @@ A `Part` object can be one of the following types:
 - **Type:** `object`
 - **Description:** Optional. A JSON Schema object describing the expected output from the tool.
 
-## Output Object
+## `OutputOptions` object
 
 ### `format`
+
 - **Type:** `string`
 - **Description:** Optional. The desired output format. All implementations should support `json` and `text` at a minimum.
 
 ### `schema`
+
 - **Type:** `object`
 - **Description:** Optional. A JSON Schema object describing the expected structure of the output.
 
-## Document Object
+## `Document` Object
 
 ### `id`
+
 - **Type:** `string`
 - **Description:** A unique identifier for the document.
 
 ### `content`
+
 - **Type:** `string`
 - **Description:** The text content of the document.
 
 ### `metadata`
+
 - **Type:** `object`
 - **Description:** Optional. Additional metadata for the document.
 
@@ -289,4 +321,4 @@ A `Part` object can be one of the following types:
 - The `context` array provides additional information that may be relevant to the task but isn't part of the direct conversation history.
 - The `candidates` field determines how many alternative responses the model should generate.
 
-This interface provides a flexible and powerful way to interact with GenAI models, supporting various types of inputs, outputs, and model configurations.
+This interface provides a flexible and powerful way to interact with GenAI models, supporting various types of inputs, outputs, and model configurations.