This change is 

@taroface there's 2 markdown files here. Please comment on them and I can adjust. The current format is bad and I think you'll have a better idea of what you want.

@mjibson Thanks for generating these. I went ahead and mocked up some Markdown templates, because it seemed easier. I'm open to your feedback on any of this:

full.md

• I like the utility of the endpoints table at the top, but it may be more efficient to make each endpoint an h2 and have them appear in the article nav.
• Is there a way to scrape the error codes for each endpoint? I made up a placeholder for this, just in case.

{{site.data.alerts.callout_success}}
This page describes...
{{site.data.alerts.end}}

## Certificates

`GET /_status/certificates/{node_id}`

Brief description of this endpoint.

<a name="cockroach.server.serverpb.CertificatesRequest"></a>
### Request Parameters

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| node_id | [string](#string) |  | node_id is a string so that "local" can be used to specify that no forwarding is necessary. |

<a name="cockroach.server.serverpb.CertificatesResponse"></a>
### Response Parameters

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| certificates | [CertificateDetails](#cockroach.server.serverpb.CertificateDetails) | repeated |  |

<a name="cockroach.server.serverpb.CertificatesError"></a>
### Error Responses

| Error | Code | Description |
| ----- | ---- | ----------- |
...

## Details

`GET /_status/details/{node_id}`

...

hotranges.md

• Assuming this is one of the endpoint pages that will be mostly manual:

---
title: HotRanges
summary: The HotRanges endpoint returns hot ranges.
toc: true
---

Description of this endpoint.

### Method

`GET /_status/hotranges`

### Example Request

...

### Request Parameters

<div>
  {% include {{ page.version.version }}/path-to-hotrangesrequest %}
</div>

### Example Response

...

### Response Parameters

<div>
  {% include {{ page.version.version }}/path-to-hotrangesresponse %}
</div>

### Error Responses

<div>
  {% include {{ page.version.version }}/path-to-hotrangeserror %}
</div>

Ok I think the full markdown will work like that. How about for the single pages one, instead of including multiple separate generated pages, it just includes a single page that has all of the request/response/error data in it? I also don't think there's a way to do error responses. Those I think happen at a higher level, like there's one generic error response or something? It's not in the proto in any case.

For e.g. hotranges.md, the reason I'd want to have separate includes is to have the request/response parameter tables come after the example request or response. Is it much harder or messier to do it this way?

RFAL. I combined the response and request sections into one for the single page template so you should be able to do it in one include. Error responses are all the same:

@mjibson Looking at #50126, are there any per-endpoint authorization parameters we can also include in the markdown files?

Nope, auth is done in go files, not listed in protos.

RFAL. Any more comments on the markdown?

bors r+

Build succeeded:

• GitHub CI (Cockroach)