Remove duplicate title heading for generated docs (#4666)

microsoft · Oct 10, 2024 · 58bd612 · 58bd612
1 parent 12c67ef
commit 58bd612
Show file tree

Hide file tree

Showing 127 changed files with 103 additions and 348 deletions.
diff --git a/docs/emitters/json-schema/guide.md b/docs/emitters/json-schema/guide.md
@@ -2,8 +2,6 @@
 title: Guide
 ---
 
-# JSON Schema files and references
-
 When a TypeSpec data type has the `@jsonSchema` decorator or is declared inside a namespace with that decorator, it is considered a _JSON Schema type_.
 
 By default, this emitter will produce one JSON Schema file per JSON Schema type. The file defines an `$id` metadata keyword based on the TypeSpec type name and the file format of the schema (for example, `Widget.yaml`). The `$id` can be overridden by using the `@id` decorator.

diff --git a/docs/emitters/json-schema/reference/data-types.md b/docs/emitters/json-schema/reference/data-types.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Data types
-
 ## TypeSpec.JsonSchema
 
 ### `Json` {#TypeSpec.JsonSchema.Json}

diff --git a/docs/emitters/json-schema/reference/decorators.md b/docs/emitters/json-schema/reference/decorators.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Decorators
-
 ## TypeSpec.JsonSchema
 
 ### `@baseUri` {#@TypeSpec.JsonSchema.baseUri}

diff --git a/docs/emitters/json-schema/reference/emitter.md b/docs/emitters/json-schema/reference/emitter.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Emitter
-
 ## Usage
 
 1. Via the command line

diff --git a/docs/emitters/json-schema/reference/index.mdx b/docs/emitters/json-schema/reference/index.mdx
@@ -8,8 +8,6 @@ toc_max_heading_level: 3
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Overview
-
 TypeSpec library for emitting TypeSpec to JSON Schema and converting JSON Schema to TypeSpec
 
 ## Install

diff --git a/docs/emitters/openapi3/cli.md b/docs/emitters/openapi3/cli.md
@@ -2,8 +2,6 @@
 title: OpenAPI3 to TypeSpec
 ---
 
-# tsp-openapi3 CLI
-
 :::warning
 The OpenAPI3 to TypeSpec conversion purpose is a one time conversion to help you get started with TypeSpec.
 The output can change in future versions of TypeSpec without being considered a breaking change.

diff --git a/docs/emitters/openapi3/diagnostics.md b/docs/emitters/openapi3/diagnostics.md
@@ -2,8 +2,6 @@
 title: Diagnostics
 ---
 
-# Diagnostics
-
 The OpenAPI emitter may produce any of the following diagnostic messages.
 
 <!-- Topics within this section should be ordered alphabetically for easy lookup -->

diff --git a/docs/emitters/openapi3/openapi.md b/docs/emitters/openapi3/openapi.md
@@ -2,8 +2,6 @@
 title: Emitter operation
 ---
 
-# Exploring the Functionality of the OpenAPI Emitter
-
 The OpenAPI emitter is designed to translate TypeSpec language elements into their corresponding OpenAPI expressions. Here's how it works:
 
 ## Server Details

diff --git a/docs/emitters/openapi3/reference/decorators.md b/docs/emitters/openapi3/reference/decorators.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Decorators
-
 ## TypeSpec.OpenAPI
 
 ### `@oneOf` {#@TypeSpec.OpenAPI.oneOf}

diff --git a/docs/emitters/openapi3/reference/emitter.md b/docs/emitters/openapi3/reference/emitter.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Emitter
-
 ## Usage
 
 1. Via the command line

diff --git a/docs/emitters/openapi3/reference/index.mdx b/docs/emitters/openapi3/reference/index.mdx
@@ -8,8 +8,6 @@ toc_max_heading_level: 3
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Overview
-
 TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec
 
 ## Install

diff --git a/docs/emitters/protobuf/guide.md b/docs/emitters/protobuf/guide.md
@@ -2,8 +2,6 @@
 title: Guide
 ---
 
-# Understanding the Protobuf Emitter
-
 TypeSpec includes a built-in emitter (`/protobuf`) that can generate Protocol Buffers specifications from TypeSpec sources. The Protobuf files generated can then be used to create gRPC services or any other tools that are compatible with Protocol Buffers.
 
 **Please note**: The Protobuf emitter is designed to work with Protocol Buffers 3 (proto3) syntax. Ensure that your workflow (including `protoc` version) supports proto3 to make full use of this emitter.

diff --git a/docs/emitters/protobuf/reference/data-types.md b/docs/emitters/protobuf/reference/data-types.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Data types
-
 ## TypeSpec.Protobuf
 
 ### `Extern` {#TypeSpec.Protobuf.Extern}

diff --git a/docs/emitters/protobuf/reference/decorators.md b/docs/emitters/protobuf/reference/decorators.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Decorators
-
 ## TypeSpec.Protobuf
 
 ### `@field` {#@TypeSpec.Protobuf.field}

diff --git a/docs/emitters/protobuf/reference/emitter.md b/docs/emitters/protobuf/reference/emitter.md
@@ -4,8 +4,6 @@ toc_min_heading_level: 2
 toc_max_heading_level: 3
 ---
 
-# Emitter
-
 ## Usage
 
 1. Via the command line

diff --git a/docs/emitters/protobuf/reference/index.mdx b/docs/emitters/protobuf/reference/index.mdx
@@ -8,8 +8,6 @@ toc_max_heading_level: 3
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Overview
-
 TypeSpec library and emitter for Protobuf (gRPC)
 
 ## Install

diff --git a/docs/extending-typespec/basics.md b/docs/extending-typespec/basics.md
@@ -3,8 +3,6 @@ id: basics
 title: Creating a TypeSpec Library
 ---
 
-# Creating a TypeSpec library
-
 A TypeSpec library is a package that includes TypeSpec types, decorators, emitters or linters. These libraries are [npm packages](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) with some additional TypeSpec-specific metadata and conventions. This guide will walk you through the process of creating a new TypeSpec library, adding types to it, and distributing it on the public npm registry. Further sections will delve into the specifics of creating [decorators](create-decorators.md), [emitters](./emitters-basics.md) and [linters](./linters.md).
 
 While this guide assumes that you'll be using [TypeScript](https://typescriptlang.org) to develop your library, you can skip the TypeScript-related steps if you prefer to use plain JavaScript.

diff --git a/docs/extending-typespec/create-decorators.md b/docs/extending-typespec/create-decorators.md
@@ -3,8 +3,6 @@ id: create-decorators
 title: Decorators
 ---
 
-# Decorators
-
 TypeSpec decorators are implemented as JavaScript functions. The process of creating a decorator can be divided into two parts:
 
 1. [Declare the decorator signature in TypeSpec](#declare-the-decorator-signature) (optional but recommended)

diff --git a/docs/extending-typespec/emitter-framework.md b/docs/extending-typespec/emitter-framework.md
@@ -3,8 +3,6 @@ id: emitter-framework
 title: Emitter framework
 ---
 
-# Emitter framework
-
 :::warning
 The emitter framework has many issues in its current form and a V2 using a completely different approach is in the works. Use with caution.
 :::

diff --git a/docs/extending-typespec/emitter-metadata-handling.md b/docs/extending-typespec/emitter-metadata-handling.md
@@ -3,8 +3,6 @@ id: emitter-metadata-handling
 title: Managing metadata and visibility in REST API emitters
 ---
 
-# Managing metadata and visibility in REST API emitters
-
 Ensuring consistent handling of [automatic visibility](../libraries/http/operations.md#automatic-visibility) and [metadata](../libraries/http/operations.md#metadata) by all REST API emitters is crucial. To understand how these features work, please refer to the TypeSpec-author documentation. This guide will help you integrate these features into your own emitter correctly.
 
 The standard `/rest` library offers a JavaScript API for emitters to interpret APIs written using its decorators. We will focus on the APIs that are specifically relevant to these features.

diff --git a/docs/extending-typespec/emitters-basics.md b/docs/extending-typespec/emitters-basics.md
@@ -3,8 +3,6 @@ id: emitters
 title: Emitters
 ---
 
-# Creating emitters
-
 TypeSpec emitters are libraries that utilize various TypeSpec compiler APIs to reflect on the TypeSpec compilation process and generate artifacts. The TypeSpec standard library includes emitters for OpenAPI version 3.0, JSON Schema, and Protocol Buffers (Protobuf). However, you might want to emit TypeSpec to a different output format. One of the main advantages of TypeSpec is its ease of use as a single source of truth for all data shapes, and the simplicity of creating an emitter contributes significantly to this.
 
 ## Emitter design

diff --git a/docs/extending-typespec/linters.md b/docs/extending-typespec/linters.md
@@ -3,8 +3,6 @@ id: linters
 title: Linters
 ---
 
-# Linters
-
 ## Linter versus `onValidate`
 
 A TypeSpec library can provide an `$onValidate` hook, which can be used to validate whether the TypeSpec program is valid according to your library's rules.

diff --git a/docs/extending-typespec/writing-scaffolding-template.md b/docs/extending-typespec/writing-scaffolding-template.md
@@ -2,8 +2,6 @@
 title: Scaffolding templates
 ---
 
-# Creating a scaffolding template
-
 TypeSpec offers a scaffolding feature through the `tsp init` command.
 
 ```bash

diff --git a/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md b/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md
@@ -4,8 +4,6 @@ title: Getting Started with TypeSpec For REST APIs
 pagination_next: getting-started/getting-started-rest/02-operations-responses # Explicitly needed as its also being the category page https://github.com/facebook/docusaurus/issues/6183
 ---
 
-# Getting Started with TypeSpec for REST APIs
-
 ## Introduction
 
 Welcome to our tutorial on using TypeSpec to define REST APIs with HTTP. In this section, we'll introduce you to TypeSpec, help you set up your environment, and cover the basic syntax and structure of TypeSpec. By the end of this section, you'll have a solid foundation to build upon in the subsequent sections.

diff --git a/docs/getting-started/getting-started-rest/02-operations-responses.md b/docs/getting-started/getting-started-rest/02-operations-responses.md
@@ -3,8 +3,6 @@ id: 02-operations-responses
 title: Operations and Responses
 ---
 
-# Operations and Responses
-
 ## Introduction
 
 In this section, we'll build upon the basics we covered in the previous section. We'll define CRUD operations (Create, Read, Update, Delete) for our Pet Store API and discuss the benefits of using nested namespaces.

diff --git a/docs/getting-started/getting-started-rest/03-handling-errors.md b/docs/getting-started/getting-started-rest/03-handling-errors.md
@@ -2,8 +2,6 @@
 title: Handling Errors
 ---
 
-# Handling Errors in Your REST API
-
 ## Introduction
 
 In this section, we'll focus on handling errors in your REST API. We'll define error models and demonstrate how to add them as possible responses to your CRUD operations.

diff --git a/docs/getting-started/getting-started-rest/04-common-parameters.md b/docs/getting-started/getting-started-rest/04-common-parameters.md
@@ -2,8 +2,6 @@
 title: Common Parameters
 ---
 
-# Reusing Common Parameters
-
 ## Introduction
 
 In this section, we'll focus on reusing common parameters in your REST API. Common parameters are parameters that are used across multiple operations. By defining these parameters once and reusing them, we can make our API more consistent, easier to read, and easier to maintain.

diff --git a/docs/getting-started/getting-started-rest/05-authentication.md b/docs/getting-started/getting-started-rest/05-authentication.md
@@ -2,8 +2,6 @@
 title: Authentication
 ---
 
-# Adding Authentication to Your REST API
-
 ## Introduction
 
 In this section, we'll focus on adding [authentication](../../libraries/http/authentication) to your REST API. We'll introduce the `@useAuth` decorator, show how to enforce authentication on specific operations, and provide an example using Bearer authentication.

diff --git a/docs/getting-started/getting-started-rest/06-versioning.md b/docs/getting-started/getting-started-rest/06-versioning.md
@@ -2,8 +2,6 @@
 title: Versioning
 ---
 
-# Versioning
-
 ## Introduction
 
 In this section, we'll focus on implementing versioning in your REST API. Versioning allows you to manage changes to your API over time without breaking existing clients. We'll introduce the `@versioned` decorator, show how to define versions with enums, and demonstrate how to use the `@added` decorator to specify version-specific models and operations.

diff --git a/docs/getting-started/getting-started-rest/07-custom-response-models.md b/docs/getting-started/getting-started-rest/07-custom-response-models.md
@@ -2,8 +2,6 @@
 title: Custom Response Models
 ---
 
-# Custom Response Models
-
 ## Introduction
 
 In this section, we'll focus on creating custom response models and demonstrate how to use them in your API operations. We'll also incorporate predefined response models from the TypeSpec HTTP library.

diff --git a/docs/getting-started/getting-started-rest/08-conclusion.md b/docs/getting-started/getting-started-rest/08-conclusion.md
@@ -2,8 +2,6 @@
 title: Conclusion
 ---
 
-# Conclusion
-
 ## Recap of Key Concepts
 
 Throughout this tutorial, we've covered a wide range of topics to help you build a comprehensive REST API using TypeSpec. Here's a brief recap of the main concepts we explored:

diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md
@@ -3,6 +3,4 @@ id: getting-started
 title: Getting Started
 ---
 
-# Getting started with TypeSpec
-
 - [Get started with TypeSpec for REST](./getting-started-rest/01-setup-basic-syntax.md)
diff --git a/docs/getting-started/typespec-for-openapi-dev.md b/docs/getting-started/typespec-for-openapi-dev.md
@@ -2,8 +2,6 @@
 title: TypeSpec For OpenAPI Developer
 ---
 
-# TypeSpec for the OpenAPI developer
-
 This guide is an introduction to TypeSpec using concepts that will be familiar to developers
 that either build or use API definitions in OpenAPI v2 or v3.
 

diff --git a/docs/handbook/cli.md b/docs/handbook/cli.md
@@ -3,8 +3,6 @@ id: cli
 title: Cli usage
 ---
 
-# Usage
-
 See full usage documentation by typing `tsp --help`:
 
 ```bash

diff --git a/docs/handbook/configuration/configuration.md b/docs/handbook/configuration/configuration.md
@@ -2,8 +2,6 @@
 title: Configuration
 ---
 
-# Compiler and library configurations
-
 The TypeSpec compiler and libraries can be configured either via a [configuration file](#configuration-file) or command line flags.
 
 ## Configuration file

diff --git a/docs/handbook/configuration/tracing.md b/docs/handbook/configuration/tracing.md
@@ -2,8 +2,6 @@
 title: Tracing
 ---
 
-# Tracing
-
 The TypeSpec Compiler, by default, builds without any debug information. The standard output is minimal, only including any `warning` or `error` diagnostics that occur during the compilation process.
 
 However, the compiler does collect additional information that can be accessed using the `--trace` command-line interface (CLI) flag.

diff --git a/docs/handbook/faq.md b/docs/handbook/faq.md
@@ -3,8 +3,6 @@ id: faq
 title: FAQ
 ---
 
-# Frequently Asked Questions (FAQ)
-
 ## I'm getting the error `Cannot find package 'x' imported from 'y'`, but I'm not using this package. Why?
 
 This issue typically arises when package 'y' has a `peerDependency` on package 'x', and package 'x' hasn't been installed. This can occur if you're using a version of npm that's older than version 7, as these older versions don't automatically install peerDependencies. You would need to install them manually.

diff --git a/docs/handbook/formatter.md b/docs/handbook/formatter.md
@@ -3,8 +3,6 @@ id: formatter
 title: Formatter
 ---
 
-# Formatter
-
 TypeSpec comes with a built-in formatter. The formatter can be used in different ways:
 
 - [Via the cli](#via-the-cli)

diff --git a/docs/handbook/releases.md b/docs/handbook/releases.md
@@ -3,8 +3,6 @@ id: releases
 title: Releases
 ---
 
-# Releases
-
 ## Versioning strategy for packages
 
 TypeSpec is currently in its development phase, and all packages are released with a `0.` major version. Each minor version may introduce some breaking changes to the TypeSpec language, library API, or both. These changes are documented [here](../release-notes).

diff --git a/docs/handbook/style-guide.md b/docs/handbook/style-guide.md
@@ -2,8 +2,6 @@
 title: Style guide
 ---
 
-# TypeSpec language style guide
-
 This guide offers a recommended set of naming conventions to follow when drafting a TypeSpec specification.
 
 :::info

diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md
@@ -4,8 +4,6 @@ title: Installation
 slug: /
 ---
 
-# Installation
-
 ## Requirements
 
 Install [Node.js 20 LTS](https://nodejs.org/en/download/) and ensure you can run the `npm` command in a command prompt:

diff --git a/docs/language-basics/alias.md b/docs/language-basics/alias.md
@@ -3,8 +3,6 @@ id: aliases
 title: Aliases
 ---
 
-# Aliases
-
 Aliases are a convenient way to define shorthand for types, especially when dealing with complex expressions. They simplify the syntax but don't have a representation in the type graph. As a result, you can't decorate aliases. If you need to give an alternate name to a model, use [`model is`](./models.md).
 
 You can define an alias using the `alias` keyword.

diff --git a/docs/language-basics/built-in-types.md b/docs/language-basics/built-in-types.md
@@ -3,8 +3,6 @@ id: built-in-types
 title: Built-in types
 ---
 
-# Built-in types
-
 TypeSpec Standard Library provide some built-in types that can be used to build more complex types.
 
 Built in types are related to each other according to the rules described in [type relations](../language-basics/type-relations.md).

diff --git a/docs/language-basics/decorators.md b/docs/language-basics/decorators.md
@@ -3,8 +3,6 @@ id: decorators
 title: Decorators
 ---
 
-# Decorators
-
 Decorators in TypeSpec allow developers to attach metadata to types within a TypeSpec program. They can also be used to compute types based on their inputs. Decorators form the core of TypeSpec's extensibility, providing the flexibility to describe a wide variety of APIs and associated metadata such as documentation, constraints, samples, and more.
 
 A range of TypeSpec constructs can be decorated, including [namespaces](./namespaces.md), [operations](./operations.md) and their parameters, and [models](./models.md) and their members.