Update H1/H2 headings throughout

www/docs/api-reference/auth-apis/api-keys.md

@@ -7,7 +7,7 @@ sidebar_label: API Keys
 API Keys can be used for querying and indexing operations, but cannot at this
 time be used for administrative operations such as creating or deleting corpora.
 
-# Creating an API Key
+## Create an API Key
 Go to [https://console.vectara.com/console/api-keys](https://console.vectara.com/console/api-keys)
 to create a new API key.  API Keys can be scoped either to be query-only or
 both query and index.  It's recommended that you choose the most limited scope
@@ -22,7 +22,8 @@ organizationally "expensive."  In general, it's recommended that you use
 
 :::
 
-# Use an API Key
+## Use an API Key
+
 To use an API key in a request, you need to pass in `x-api-key` as an HTTP
 header.
 

www/docs/api-reference/auth-apis/oauth.md

@@ -28,12 +28,12 @@ OAuth 2.0 has several advantages over API keys or simple usernames/passwords:
 
 :::
 
-# Creating an application client
+## Create an application client
 Go to [https://console.vectara.com/console/authentication/app-client](https://console.vectara.com/console/authentication/app-client)
 to create a new application client.  Most applications will want to use the
 `Client Credentials` grant.
 
-# Obtain a JWT Token
+## Obtain a JWT Token
 Before continuing, you'll need the OAuth 2.0 token endpoint.  You can obtain that
 by navigating to the [Authentication page](https://console.vectara.com/authentication)
 and then selecting the App Client tab.  Append `/oauth2/token` to this URL and

www/docs/api-reference/indexing-apis/deleting_documents.md

@@ -44,7 +44,7 @@ retry may not succeed.
 - `UNAVAILABLE`: The service is temporarily unavailable, and the operation should be retried,
 preferably with a backoff. Note that the deletion operation is idempotent, so it is fine to re-apply.
 
-### Example
+### Delete a Document Example
 
 The code snippet below illustrates how to delete a document from a corpus. For information
 on how to get the call credentials and metadata, please consult

www/docs/api-reference/indexing-apis/file-upload/file_formats.md

@@ -13,7 +13,7 @@ to individual sections within it.
 
 Below is a sample document in each format.
 
-## JSON
+## Sample JSON Document
 
 ```json
 {
@@ -44,7 +44,7 @@ Below is a sample document in each format.
 }
 ```
 
-## Pbtxt
+## Sample Pbtxt Document
 
 ```
 document_id: "selected-works-of-shakespeare"
@@ -69,7 +69,7 @@ section {
 }
 ```
 
-## Python
+## Sample Python Document
 
 For reference, these documents were output by the following Python program:
 

www/docs/api-reference/indexing-apis/file-upload/supported_file_formats.md

@@ -6,7 +6,7 @@ title: Supported File Types
 import {Config} from '@site/docs/definitions.md';
 import {vars} from '@site/static/variables.json';
 
-## Binary file types
+## Raw document types
 
 The upload endpoint supports several raw document types. Vectara extracts text
 from these documents and sections them as best it can. This provides a
@@ -20,19 +20,19 @@ types are supported:
 - Microsoft Word (`doc`, `docx`).
 - Microsoft Powerpoint (`ppt`, `pptx`).
 - Text files (`txt`).
-- HTML files.
-- LXML files.
-- RTF files.
-- ePUB files.
+- HTML files (`.html`).
+- LXML files (`.lxml`).
+- RTF files (`.rtf`).
+- ePUB files (`.epub`).
 - Email files conforming to RFC 822.
 
-## Semi-structured
+## Semi-structured documents
 
 In addition, the [upload endpoint](/docs/api-reference/indexing-apis/file-upload/file-upload) supports
 sending semi-structured documents through this endpoint that reflect a
 `Document` proto message.  Those can be sent in the following formats:
 
--  `pb`: Contains binary serialized `Document` proto message.
+- `pb`: Contains binary serialized `Document` proto message.
 
 - `pbtxt`: Contains `Document` proto message in proto text format.
 

www/docs/api-reference/indexing-apis/indexing.md

@@ -64,7 +64,7 @@ message IndexDocumentResponse {
 }
 ```
 
-### Document
+### Document Definition in Vectara
 
 A document is a piece of coherent textual matter. It defines an ID,
 **document_id**, which must be unique among all the documents in

www/docs/api-reference/overview.md

@@ -6,11 +6,11 @@ sidebar_label: API Overview
 
 import {Config} from '@site/docs/definitions.md';
 
-Everything in <Config v="names.product"/> is driven by APIs.  This page serves
+Everything in <Config v="names.product"/> is driven by APIs. This page serves
 as an overview of the APIs and how to navigate this documentation to use those
 APIs.
 
-# gRPC and REST
+## gRPC and REST APIs
 Almost every API has both a [gRPC](https://en.wikipedia.org/wiki/GRPC) and a
 REST(https://en.wikipedia.org/wiki/Representational_state_transfer) endpoint.
 The 1 exception to this is the [File Upload](/docs/api-reference/indexing-apis/file-upload/file-upload)
@@ -23,11 +23,11 @@ gRPC has several advantages over REST:
 However, we include REST APIs as there's a lot of developer tooling around REST
 APIs and some organizations still struggle with using HTTP/2.0 due to firewalls.
 
-## REST
+### REST API
 If you'd like more details about how to use our REST APIs, including details on
 our OpenAPI specification and services, a good place to start is the [REST](rest)
 page.
 
-## gRPC
+### gRPC API
 If you'd like more details about how to use our gRPC APIs, including details on
 how to generate strongly typed clients, see our [gRPC](protobuf-definitions) page.

www/docs/api-reference/protobuf-definitions.md

@@ -37,7 +37,7 @@ proto $ curl -s -o ext/google/api/http.proto --create-dirs \
              https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto
 ```
 
-## Examples
+## Example Protocol Buffers
 
 The [Quickstart Examples](https://github.com/vectara/getting-started) GitHub
 repository has examples of connecting via gRPC in a variety of languages.

www/docs/api-reference/rest.md

@@ -9,7 +9,7 @@ import {Config} from '@site/docs/definitions.md';
 While gRPC provides low latency and excellent scalability, in some scenarios
 it may be simpler to integrate using REST APIs.
 
-# API Formatting Guidelines
+## API Formatting Guidelines
 All of the APIs can be found at https://<Config v="domains.rest.admin"/>/&lt;version&gt;/&lt;api-endpoint&gt;ee
 
 The API endpoints are outlined in the various subsections of this API Reference
@@ -23,13 +23,13 @@ from the protobuf definitions to REST is:
 - API parameters can be sent in either `camelCase` or lowercase with `underscores`.  For example, you could submit either `numResults` or `num_results` in the Search API
 - JSON responses are always returned in `camelCase` form
 
-# Authentication
+## API Authentication
 All <Config v="names.product"/> APIs are authenticated.  Indexing and Search
 APIs can be authenticated via [API Keys](/docs/common-use-cases/app-authn-authz/api-keys)
 however, Admin actions (creating/deleting corpora) must be done via
 [OAuth 2.0](/docs/api-reference/auth-apis/oauth-2).
 
-# API Playground and OpenAPI Specifications
+## API Playground and OpenAPI Specifications
 You can find up-to-date OpenAPI specifications at
 [https://docs.vectara.com/vectara-oas.yaml](https://docs.vectara.com/vectara-oas.yaml).
 These are automatically derived from the gRPC protobuf definitions as well.

www/docs/api-reference/search-apis/batched-queries.md

@@ -38,10 +38,10 @@ separate query for billing purposes.
 
 :::
 
-# Responses
+## Responses
 
-When you a query <Config v="names.product"/>, you get back an array oof results
-This is to assist in using a
+When you a query <Config v="names.product"/>, you get back an array of results.
+This array is to assist in using
 [Batched Query](/docs/api-reference/search-apis/batched-queries.md), 
 
 ```jsx

www/docs/api-reference/search-apis/exact-boolean-text-matches.md

@@ -15,7 +15,7 @@ term was absent from Vectara's training data (e.g. product SKUs)
 - Incorporate typical keyword modifiers like a `NOT` function, exact phrase
 matching, and wildcard prefixes of terms
 
-# Enabling Exact and Boolean Text Matching
+## Enable Exact and Boolean Text Matching
 By default, the exact and Boolean text matching is disabled and only neural
 retrieval is used.  You can enable the feature by specifying a value,
 `lambda`, at query time.  This value can range from `0` to `1` (inclusive).
@@ -34,7 +34,7 @@ the scores of the results of the two different scoring models.  Users often see
 best results by setting this value somewhere between 0.01 and 0.1, and we
 typically recommend users start experimentation with a value of 0.025.
 
-# Syntax
+## Syntax Interpretation
 When interpreting query strings, Vectara treats the following syntax specially.
 
 Words that are quoted must match exactly in that order. So, for example, the

www/docs/common-use-cases/app-authn-authz/authorization.md

@@ -14,10 +14,10 @@ identity by presenting a valid JWT token. Even entities that lack explicit roles
 may still be able to perform operations on the platform through the use of
 **default permissions**.
 
-These concepts are explained in further detail in the sections below.
-
 ## Roles
 
+This section explains these concepts in further detail:
+
 ### Account Level Roles
 
 - **Owner** is initially granted to whoever created the account. It grants

www/docs/common-use-cases/app-authn-authz/create_api_keys.md

@@ -26,7 +26,7 @@ Administrative actions cannot be performed through these keys.
 
 The remainder of this guide walks you through managing and using the API Keys.
 
-## Creating a Key
+## Create an API Key
 
 If you have the necessary permissions you'll see the `API Keys` in the sidebar.
 Click on it and you'll see the following page
@@ -51,7 +51,7 @@ You can now start using the key.
 
 :::
 
-## Using a Key
+## Use an API Key
 
 To use an API key, pass it using the `x-api-key` header request.
 
@@ -147,7 +147,9 @@ END
 
 ## Management
 
-### Disable and Enable
+This section describes how to manage API keys.
+
+### Disable and Enable API Keys
 
 To temporarily disable access to an API key, begin by visiting the API Keys
 screen. Select disable by clicking on the action menu (three dots) of the key
@@ -160,7 +162,7 @@ It will take around a minute for query requests using this key to be blocked.
 Once disabled, a key can be reenabled through the action menu. It will take a
 minute or two before it can serve query traffic again.
 
-### Delete
+### Delete API Keys
 
 A key may be permanently deleted through its action menu. Proceed with caution,
 once deleted, there is no way to undelete it, and all external systems that

www/docs/common-use-cases/batched-queries.md

@@ -38,9 +38,9 @@ separate query for billing purposes.
 
 :::
 
-# Responses
+## Responses
 
-When you a query <Config v="names.product"/>, you get back an array oof results
+When you a query <Config v="names.product"/>, you get back an array of results
 This is to assist in using a
 [Batched Query](/docs/api-reference/search-apis/batched-queries.md), 
 

www/docs/common-use-cases/filtering-by-metadata/built_in_filterable_metadata.md

@@ -6,13 +6,13 @@ title: Default Filterable Metadata
 import {Config} from '@site/docs/definitions.md';
 
 A few pieces of metadata are filterable out of the box, as they're very
-useful in a variety of situations.  This page describes these.
+useful in a variety of situations. This page describes these.
 
 Note that you can set up additional fields to filter on by setting up
 [filter attributes](/docs/api-reference/admin-apis/create-corpus#filter-attribute) on a
 corpus.
 
-## part.lang
+## `part.lang` field
 Each section of a document is evaluated for its language at index time and the
 `part.lang` field is added with a 3-character lower-case language code
 ([ISO 639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes)).  For
@@ -24,7 +24,7 @@ Valid filter expressions for this would be something like:
 * `part.lang = 'deu'`
 * `part.lang = 'eng' OR part.lang = 'deu'`
 
-## part.is_title
+## `part.is_title` field
 When adding content, <Config v="names.product"/> will add a special Boolean
 field to indicate whether the field is a title field or not.  This is useful
 for a few different cases depending on how you model your data.  For example,

www/docs/common-use-cases/keeping-your-data-private/data_encryption.md

@@ -90,7 +90,7 @@ The key should look like the following:
 
 The final step to creating the AWS KMS key to finish the key creation.
 
-## Attach your key to your account
+## Attach your AWS KMS key to your account
 In order to get <Config v="names.product"/> to use your key, you must
 contact <Config v="names.company"/> Support.  Send us the ARN for the KMS key
 you created (starting with `arn:aws:kms:us-west-2`).
@@ -99,11 +99,11 @@ The <Config v="names.company"/> team will set the configuration up for you. In
 the future, you will be able to set the ARN on the <Config v="names.product"/>
 Console and these instructions will be updated.
 
-## How does it work
+## How the encryption key works
 Once your AWS KMS key is configured in the platform, when encrypting your
 document text or metadata, <Config v="names.product"/> will connect to your KMS
 service to generate an encryption key. The encryption key provided by the KMS
 is stored in-memory and used to encrypt and decrypt your data. In-memory key
-will expire every hour.  In turn, every hour <Config v="names.product"/> will
+will expire every hour. In turn, every hour <Config v="names.product"/> will
 ask your AWS KMS to generate that encryption key again.
 

www/docs/common-use-cases/keeping-your-data-private/textless.md

@@ -8,13 +8,15 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import {Config} from '@site/docs/definitions.md';
 
-## Textless
 When you create a corpus [via the API](/docs/api-reference/admin-apis/create-corpus) or the
 [UI](/docs/console-ui/creating-a-corpus), you will have the option to create it
-and "don't store the text," also known as a "textless" mode.  When this is
-enabled, several things happen in the platform.  This document talks about when
-it's appropriate to enable textless, what happens on the platform, and what
-benefits and limitations it brings.
+and "don't store the text," also known as a "textless" mode.  
+
+## Textless Mode
+
+When you enable textless mode, several things happen in the platform.  
+Let's look at when it's appropriate to enable textless, what happens on the 
+platform, and what benefits and limitations it brings.
 
 ## What happens when textless is enabled
 When you enable `textless` on a corpus, <Config v="names.product"/> discards
@@ -28,7 +30,7 @@ retrieve the document from a separate system of record based on the ID to show
 it and also allows <Config v="names.product"/> to perform any metadata-based
 filtering on the document.
 
-## Use cases
+### Textless mode use cases
 One use case for `textless` is when you have very sensitive text content.  By
 enabling this feature, the text content becomes unrecoverable
 to <Config v="names.company"/> or to any user that manages to query for and
@@ -38,7 +40,7 @@ In general, this feature is optimal for use cases where the cost of any
 information leakage is very high.  Note that <Config v="names.product"/> does
 [encrypt documents](encryption)
 
-## Limitations
+### Limitations
 Currently, the [reranking](/docs/api-reference/search-apis/reranking) capability relies on
 the text being stored.  As a result, attempting to rerank search results on any
 corpora where text storage has been turned off will not work at this time.

www/docs/common-use-cases/question-answer/overview.md

@@ -16,7 +16,7 @@ build very tight controls for the types of questions users can ask and get
 authoritative answers to.  These can be great for building things like
 RFP-answering systems for employees and FAQ lookups for customers.
 
-# Formatting data for indexing
+## Format data for indexing
 When you send data to <Config v="names.product"/> for this use case, we
 recommend that you index the question in the `title` field and the answer to
 that question in the text content.  For example:
@@ -37,7 +37,7 @@ that question in the text content.  For example:
 }
 ```
 
-# Querying for similar questions
+## Query for similar questions
 Suppose you wanted to find the answer to a question related to this example.
 You can put <Config v="names.product"/> into a document-matching mode by
 setting `semantics` to `RESPONSE`.  For example:
@@ -67,7 +67,7 @@ instead tells it to find similar questions.
 You can also add a [filter expression](/docs/common-use-cases/filtering-by-metadata/filter-overview)
 of `part.is_title = true` to *only* match the questions.
 
-# Combining question matching and answering
+## Combine question matching and answering
 Expanding on the previous example, we can help users find question or answer
 matches together by using [batched queries](/docs/api-reference/search-apis/batched-queries)
 combined with filter expressions.  For example: