CMR-11239: Successfully implemented Astro/Starlight and generated a basic documentation site (total setup time ~= 1 hour)

Author: bmsultz-nasa

search-app/docs/astro.config.mjs

@@ -5,6 +5,6 @@ import starlight from "@astrojs/starlight";
 // https://astro.build/config
 export default defineConfig({
   integrations: [starlight({
-    title: 'Table of Contents'
+    title: 'CMR API Documentation'
   })]
 });

…ch-app/docs/src/content/docs/requests.md …-app/docs/src/content/docs/1-requests.mdsearch-app/docs/src/content/docs/requests.md renamed to search-app/docs/src/content/docs/1-requests.md search-app/docs/src/content/docs/requests.md renamed to search-app/docs/src/content/docs/1-requests.md

@@ -3,17 +3,17 @@ title: Requests
 description: Provides foundational request information for the CMR API.
 ---
 
-### <a name="general-request-details"></a> General Request Details
+## <a name="general-request-details"></a> General Request Details
 
-#### <a name="maximum-url-length"></a> Maximum URL Length
+### <a name="maximum-url-length"></a> Maximum URL Length
 
 The Maximum URL Length supported by CMR is indirectly controlled by the Request Header Size setting in Jetty which is set to 1MB. This translates to roughly 500k characters, however it is recommended that any GET request be limited to 6,000 characters, and in a web browser the recommended length is no longer than 2000 characters. Clients using the Search API with query parameters should be careful not to exceed this limit or they will get an HTTP response of 413 FULL HEAD. If a client expects that the query url could be extra long so that it exceeds 6k characters, they should use the POST API for searching.
 
-#### <a name="cors-header-support"></a> CORS Header support
+### <a name="cors-header-support"></a> CORS Header support
 
 The CORS headers are supported on search endpoints. Check [CORS Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) for an explanation of CORS headers. Custom CORS request headers supported are Authorization, Client-Id, CMR-Request-Id, X-Request-Id, CMR-Scroll-Id (**deprecated**) and CMR-Search-After. Custom response headers supported are CMR-Hits, CMR-Request-Id, X-Request-Id, CMR-Scroll-Id (**deprecated**), CMR-Search-After, CMR-Timed-Out, CMR-Shapefile-Original-Point-Count and CMR-Shapefile-Simplified-Point-Count.
 
-#### <a name="query-parameters"></a> Query Parameters
+### <a name="query-parameters"></a> Query Parameters
 
  * `page_size` - Number of results per page - default is 10, max is 2000.
  * `page_num` - The page number to return. (**deprecated**)
@@ -24,7 +24,7 @@ The CORS headers are supported on search endpoints. Check [CORS Documentation](h
  * `token` - Specifies a user token from EDL or Launchpad for use as authentication. Using the standard [Authorization header](#headers) is the prefered way to supply a token. This parameter may be deprecated in the future.
  * `echo_compatible` - When set to true results will be returned in an ECHO compatible format. This mostly removes fields and features specific to the CMR such as revision id, granule counts and facets in collection results. Metadata format style results will also use ECHO style names for concept ids such as `echo_granule_id` and `echo_dataset_id`.
 
-#### <a name="paging-details"></a> Paging Details
+### <a name="paging-details"></a> Paging Details
 
 __NOTE:__ Deep paging is being deprecated in favor of [Search After](#search-after). Please switch your scroll based queries to [Search After](#search-after) which is more efficient and easier to use.
 
@@ -38,7 +38,7 @@ __Note__: In the event which an ingest or delete occurs between paging requests,
 
 You can not page past the 1 millionth item. Please contact the CMR Team at cmr-support@nasa.gov if you need to retrieve items in excess of 1 million from the CMR. Additionally granule queries which do not target a set of collections are limited to paging up to the 10,000th item.
 
-#### <a name="search-after"></a> Search After
+### <a name="search-after"></a> Search After
 
 __NOTE__: This is currently the prefered way to request large sets of records.
 
@@ -79,7 +79,7 @@ curl -i -H 'CMR-Search-After: ["xyz", 789, 999]' "%CMR-ENDPOINT%/granules?concep
 ```
 There will be only 8 granules in the result set. We can deem the search has reached the end because the number of results returned is less than the page_size, but if we search again with the new `CMR-Search-After` header value returned, we will get an empty result set and there won't be a `CMR-Search-After` header in the response.
 
-#### <a name="scrolling-details"></a> Scrolling Details
+### <a name="scrolling-details"></a> Scrolling Details
 
 __IMPORTANT:__ Scrolling is deprecated and will be disabled in the future. When disabled, requests using CMR-Scroll-Id or scroll parameter will return HTTP 400 errors with instructions to migrate to [Search After](#search-after). Please migrate your applications to use the Search After pattern instead, which is more efficient and easier to use.
 
@@ -93,7 +93,7 @@ When all the results have been returned subsequent calls using the same `CMR-Scr
 
 Important note: Clients using scrolling (especially via programmatic API or scripts) should explicitly invoke [`clear scroll session`] (#clear-scroll) to release the scroll session when they are finished. This will end the scroll session and free up system resources.
 
-#### <a name="parameter-options"></a> Parameter Options
+### <a name="parameter-options"></a> Parameter Options
 
 The behavior of search with respect to each parameter can be modified using the `options` parameter. The `options` parameter takes the following form:
 
@@ -106,7 +106,7 @@ where parameter is the URL parameter whose behavior is to be affected, value is
  * `and` - if set to true and if multiple values are listed for the param, the concepts must have ALL of these values in order to match. The default is `false` which means concepts with ANY of the values match. This option only applies to fields which may be multi-valued; these are documented here.
  * `or` - this option only applies to granule attributes or science-keywords searches. If set to true, the collection/granule will match when any of the grouped search condition is matched. The default is false.
 
-##### <a name="collection-result-features"></a> Collection Result Feature Parameters
+#### <a name="collection-result-features"></a> Collection Result Feature Parameters
 
 These are query parameters that control what extra data is included with collection search results. They do not impact which collections are matched but can add additional data to the search results like facets, granule counts, and tags.
 
@@ -124,9 +124,9 @@ These are query parameters that control what extra data is included with collect
   _The `include_highlights` feature is only supported for the JSON response format and only applies to keyword searches._
 
 
-#### <a name="headers"></a> HTTP Headers
+### <a name="headers"></a> HTTP Headers
 
-##### Request Headers
+#### Request Headers
 `Accept` - specifies the MimeType to return search results in. Default is "application/xml".
 
     `curl -H "Accept: application/xml" -i "%CMR-ENDPOINT%/collections"`
@@ -147,7 +147,7 @@ These are query parameters that control what extra data is included with collect
 
 `CMR-Request-Id` - This header serves the same purpose as `X-Request-Id` header. It is kept to support legacy systems.
 
-##### The response headers
+#### The response headers
 
 * `CMR-Hits` and `CMR-Took` indicate the number of result hits and the time to build and execute the query, respectively.
 * `CMR-Request-Id` and `X-Request-Id` return the same value - the value passed in through `CMR-Request-Id` request header or `X-Request-Id` request header or a unique id generated for the client request when no value is passed in, This can be used to help debug client errors.
@@ -156,7 +156,7 @@ These are query parameters that control what extra data is included with collect
 * `content-md5` returns the MD5 hash of the content.
 * `content-sha1` returns the SHA1 hash value for the content.
 
-#### <a name="extensions"></a> Extensions
+### <a name="extensions"></a> Extensions
 
 Besides MimeTypes, client can also use extensions to specify the format for search results. Default is xml.
 
@@ -189,13 +189,13 @@ Here is a list of supported extensions and their corresponding MimeTypes:
 
   __NOTE__: As of version "%CMR-RELEASE-VERSION%", the latest UMM Collection version is `%COLLECTION-UMM-VERSION%`.
 
-#### <a name="request-timeouts"></a> Request Timeouts
+### <a name="request-timeouts"></a> Request Timeouts
 
 The CMR operating environment imposes a hard limit of 180 seconds on any request, after which a 504 error is
 returned. To avoid this, the CMR has an internal query timeout of 170 seconds - any query taking longer will time
 out and a subset of the total hit results will be returned instead of an error. The response for queries that time
 out will include the `CMR-Time-Out` header set to `true`.
 
-#### <a name="request-moderation"></a> Moderating Client Request Traffic
+### <a name="request-moderation"></a> Moderating Client Request Traffic
 
 In order to provide robust availability and performance for all clients of the service, CMR Search deploys a set of rate throttling rules for request traffic. These rules are defined to target specific request signatures, throttling the allowed rate of these searches in an effort to prevent overall degradation of system performance and availability. If a client request should exceed one of these rate throttling rules, the request will be rejected and a `429` error status returned to the client along with a `retry-after` header value. The suggested practice for any CMR Search client is to honor the `retry-after` header value and delay accordingly before re-issuing the failed request and continuing with its CMR Search processing.

…h-app/docs/src/content/docs/searching.md …app/docs/src/content/docs/2-searching.mdsearch-app/docs/src/content/docs/searching.md renamed to search-app/docs/src/content/docs/2-searching.md search-app/docs/src/content/docs/searching.md renamed to search-app/docs/src/content/docs/2-searching.md

@@ -3,13 +3,13 @@ title: Searching
 description: Provides information on general methods of searching with the CMR API, as well as the formats that will be used for search results.
 ---
 
-### <a name="search-with-post"></a> Search with POST
+## <a name="search-with-post"></a> Search with POST
 
 Search collections or granules with query parameters encoded form in POST request body.
 
     curl -i -XPOST %CMR-ENDPOINT%/collections -d "dataset_id[]=Example%20DatasetId&dataset_id[]=Dataset2"
 
-### <a name="search-with-json-query"></a> Search with JSON Query
+## <a name="search-with-json-query"></a> Search with JSON Query
 
 Search for collections or granules with JSON in a POST request body. The JSON must conform to the schema
 that is defined in `%CMR-ENDPOINT%/site/CollectionJSONQueryLanguage.json` or `%CMR-ENDPOINT%/site/GranuleJSONQueryLanguage.json`
@@ -29,7 +29,7 @@ for collections and granules respectively. Only collection and granule search ar
                                 { "bounding_box": [-45,15,0,25],
                                   "short_name": "Short_name 1"}]}}'
 
-### <a name="search-with-aql"></a> Search with AQL
+## <a name="search-with-aql"></a> Search with AQL
 
 Search collections or granules with AQL in POST request body. The AQL must conform to the schema
 that is defined in `%CMR-ENDPOINT%/site/IIMSAQLQueryLanguage.xsd`.
@@ -38,7 +38,7 @@ that is defined in `%CMR-ENDPOINT%/site/IIMSAQLQueryLanguage.xsd`.
     <query><for value="collections"/><dataCenterId><all/></dataCenterId>
     <where><collectionCondition><shortName><value>S1</value></shortName></collectionCondition></where></query>'
 
-### <a name="temporal-range-searches"></a> Temporal Range searches
+## <a name="temporal-range-searches"></a> Temporal Range searches
 
 A couple of parameters used in search expect a date range as input. For example, the parameter "temporal" used in collection and granule searches and the parameter "equator_crossing_longitude" used in granule searches both accept date ranges. All these parameters expect temporal ranges in the same format. The temporal ranges can be specified as a pair of date-time values separated by comma(,). Exactly one of the two bounds of the interval can be omitted. In addition to comma separated values, one can also specify temporal ranges as [ISO 8601 time intervals](https://en.wikipedia.org/?title=ISO_8601#Time_intervals). Some examples of valid temporal range values are:
 
@@ -54,7 +54,7 @@ A couple of parameters used in search expect a date range as input. For example,
 
 __Note__: ISO 8601 does not allow open-ended time intervals but the CMR API does allow specification of intervals which are open ended on one side. For example, `2000-01-01T10:00:00Z/` and `/2000-01-01T10:00:00Z` are valid ranges.
 
-### <a name="search-for-tiles"></a> Search for Tiles
+## <a name="search-for-tiles"></a> Search for Tiles
 
 Tiles are geographic regions formed by splitting the world into rectangular regions in a projected coordinate system such as Sinusoidal Projection based off an Authalic Sphere. CMR supports searching of tiles which fall within a geographic region defined by a given input geometry. Currently, only tiles in MODIS Integerized Sinusoidal Grid(click [here](https://lpdaac.usgs.gov/products/modis_products_table/modis_overview) for more details on the grid) can be searched. The input geometry could be either a minimum bounding rectangle or one of point, line or polygon in spherical coordinates. The input coordinates are to be supplied in the same format as in granule and collection spatial searches (See under "Find granules by Spatial").
 
@@ -79,7 +79,7 @@ Find all the tiles which a line intersects.
 
 The output of these requests is a list of tuples containing tile coordinates, e.g: [[16,8],[16,9],[17,8],[17,9]], in the JSON format. The first value in each tuple is the horizontal grid coordinate(h), i.e. along east-west and the second value is the vertical grid coordinate(v), i.e. along north-south.
 
-### <a name="retrieve-controlled-keywords"></a> Retrieve Controlled Keywords
+## <a name="retrieve-controlled-keywords"></a> Retrieve Controlled Keywords
 
 The keyword endpoint is used to retrieve the full list of keywords for each of the controlled vocabulary fields. The controlled vocabulary is cached within CMR, but the actual source is the GCMD Keyword Management System (KMS). Users of this endpoint are interested in knowing what the CMR considers as the current controlled vocabulary, since it is the cached CMR values that will eventually be enforced on CMR ingest.
 
@@ -171,9 +171,9 @@ Note: Search parameter filtering are not supported - requests are rejected when
 }
 ```
 
-### <a name="supported-result-formats"></a> Supported Result Formats
+## <a name="supported-result-formats"></a> Supported Result Formats
 
-#### <a name="html"></a> HTML
+### <a name="html"></a> HTML
 
 The HTML response format is intended to be used only in a web browser to view a single collection record. The collection html representation can be viewed by putting the following in the web browser address bar.
 
@@ -186,7 +186,7 @@ For private collection, an EDL bearer token or a Launchpad token can be used to
 %CMR-ENDPOINT%/concepts/<concept-id>?token=EDL-xxxxxx
 ```
 
-#### <a name="atom"></a> Atom XML
+### <a name="atom"></a> Atom XML
 
 See the [Atom specification](http://tools.ietf.org/html/rfc4287) for a full description of Atom.
 
@@ -301,7 +301,7 @@ __Example__
 </feed>
 ```
 
-#### <a name="csv"></a> CSV
+### <a name="csv"></a> CSV
 
 The comma separated value (CSV) format is supported for collections and granules.
 Version and Processing Level are strings. When importing into the spreadsheet, please specify text as their column types. This will prevent version "004" to be displayed as "4" in the spreadsheet.
@@ -321,7 +321,7 @@ Granule UR,Producer Granule ID,Start Time,End Time,Online Access URLs,Browse URL
 SC:SPL1AA.001:12345,SMAP_L1C_S0_HIRES_00016_A_20150530T160100_R03001_001.h5,,,,,,,
 ```
 
-#### Metadata Responses (DIF, DIF 10, ECHO 10, ISO-SMAP, ISO-MENDS)
+### Metadata Responses (DIF, DIF 10, ECHO 10, ISO-SMAP, ISO-MENDS)
 
 All of the XML Metadata formats (except the XML used in returning references only) have the same structure, differing only in the way each result is returned. These formats return a single XML document with a `<results>` XML element containing the following fields as sub-elements:
 
@@ -339,7 +339,7 @@ The results are returned as a sequence of `<result>` XML elements, the contents
 | format      | the mime-type for the returned metadata       |
 | revision-id | the CMR revision number of the stored concept |
 
-#### <a name="dif-9"></a> DIF 9
+### <a name="dif-9"></a> DIF 9
 
 __NOTE:__ The DIF 9 format is being __deprecated__ in favor of DIF 10. While it is still supported, we strongly discourage its use for new metadata.
 
@@ -386,7 +386,7 @@ __Example__
 </results>
 ```
 
-#### <a name="dif-10"></a> DIF 10
+### <a name="dif-10"></a> DIF 10
 
 See the [specification](https://cdn.earthdata.nasa.gov/dif/10.x/) for details.
 
@@ -454,7 +454,7 @@ __Example__
 </results>
 ```
 
-#### <a name="echo-10"></a> ECHO 10
+### <a name="echo-10"></a> ECHO 10
 
 See the [specification](https://cdn.earthdata.nasa.gov/echo/schemas/10.0/) for details.
 
@@ -492,7 +492,7 @@ __Example__
 </results>
 ```
 
-#### <a name="iso-mends"></a> ISO-MENDS (ISO-19115-2)
+### <a name="iso-mends"></a> ISO-MENDS (ISO-19115-2)
 
 See the [specification](https://cdn.earthdata.nasa.gov/iso/)
 
@@ -591,7 +591,7 @@ __Example__
 </results>
 ```
 
-#### <a name="iso-smap"></a> ISO-SMAP
+### <a name="iso-smap"></a> ISO-SMAP
 
 See the [specification](https://cdn.earthdata.nasa.gov/iso/)
 
@@ -677,7 +677,7 @@ __Example__
 </results>
 ```
 
-#### <a name="json"></a> ATOM JSON
+### <a name="json"></a> ATOM JSON
 
 The JSON response contains all the fields in the *ATOM* response, plus the the following fields:
 
@@ -770,7 +770,7 @@ __Example__
 }
 ```
 
-#### <a name="umm-json"></a> UMM JSON
+### <a name="umm-json"></a> UMM JSON
 
 The UMM JSON response, unlike ATOM JSON, contains "meta-metadata" of the collection and the UMM fields. The UMM JSON format is applicable to collection, granule, variable, service and tool searches. The UMM-JSON response is helpful if you wish to get the native-id of a concept after ingesting it. The version of the UMM returned will be the version requested or the latest version. Clients are recommended to always specify a version to avoid breaking changes in UMM.
 
@@ -903,7 +903,7 @@ __Example__
 
 A collection containing "\_errors" is not valid UMM and cannot be ingested into the CMR.
 
-#### <a name="kml"></a> KML
+### <a name="kml"></a> KML
 
 KML is the [XML language](http://www.opengeospatial.org/standards/kml) used by the Google Earth application and is used by the CMR to return spatial data associated with a collection or granule.
 
@@ -959,7 +959,7 @@ __Example__
 </kml>
 ```
 
-#### <a name="open-data"></a> Open Data
+### <a name="open-data"></a> Open Data
 
 The Open Data format was developed as part of [Project Open Data](https://project-open-data.cio.gov) in an attempt to make data more accessible. See the Open Data [schema](https://project-open-data.cio.gov/v1.1/schema/) for details.
 
@@ -997,7 +997,7 @@ __Example__
 }
 ```
 
-#### <a name="stac"></a> STAC
+### <a name="stac"></a> STAC
 
 The STAC (SpatioTemporal Asset Catalog) result format is a specification for describing geospatial data with JSON and GeoJSON. The related STAC-API specification defines an API for searching and browsing STAC catalogs. See the [STAC Specification](https://stacspec.org/) for details.
 
@@ -1190,7 +1190,7 @@ __Granule Retrieval in STAC Format Response Example via POST__
   }
 }
 ```
-#### <a name="xml-reference"></a> XML
+### <a name="xml-reference"></a> XML
 
 The XML response format is used for returning references to search results. It consists of the following fields: