Gitbook + GitHub Open Questions

[sybohy]

Editing docs inside of Gitbook's web editor is tedious and error-prone. We're exploring making use of Gitbook's sync feature.

A few questions that I'll check off once we have sufficiently good answers:

• [x] Can we set the structure of the menu/content?
• [x] Where should images be hosted if referenced in markdown?
• [x] How to interlink content?
• [x] Can we create code blocks with tabs?
• [x] How are open-api specs specified in markdown?
• [x] Does the Gitbook+Github sync approach present any advantage over just using Docsaurus 2.0?

[sybohy]

Structuring content is easy. You just create a SUMMARY.md file and follow its structure. More or less like docsaurus

‌# Summary​

## Getting Started

- [Get API Key](quickstart/get-api-key.md)
- [Installation](quickstart/installation.md)
- [Authentication](quickstart/authentication.md)

## Core Concepts

[sybohy]

Creating multiple code block with tabs also pretty straight forward but a bit messy. I think this will be a solid first candidate for some sort of post-processing where the markdown does not include the actually code. Example below

current

Proposed Approach With Post Processor

Basically drop in a post processing tag with a reference to some code elsewhere in the code base. Can do a quick prototype later.

## hello world
{% code_sample_with_tabs_xyz %}

[sybohy]

OpenAPI spec works like a charm:

# API

{% swagger src="https://connect.getseam.com/openapi.json" path="/index" method="get" %}
[https://connect.getseam.com/openapi.json](https://connect.getseam.com/openapi.json)
{% endswagger %}

{% swagger src="https://connect.getseam.com/openapi.json" path="/access_codes/get" method="get" %}
[https://connect.getseam.com/openapi.json](https://connect.getseam.com/openapi.json)
{% endswagger %}

{% swagger src="https://connect.getseam.com/openapi.json" path="/access_codes/update" method="put" %}
[https://connect.getseam.com/openapi.json](https://connect.getseam.com/openapi.json)
{% endswagger %}

{% swagger src="https://connect.getseam.com/openapi.json" path="/action_attempts/get" method="get" %}
[https://connect.getseam.com/openapi.json](https://connect.getseam.com/openapi.json)
{% endswagger %}

[sybohy]

Linking between pages and sections seems pretty straight-forward.

Between two pages in the same section

go back to the previous page in this section on getting your [API Key](get-api-key.md) .

make sure to read our guide on getting your [API Key](../quickstart/get-api-key.md) in this other section.

[sybohy]

Images are so-so.

So basically, anything you upload on Gitbook will be added under .gitbook/assets. Unfortunately, anything you add manually under .gitbook/assets doesn't show up an option on Gitbook ui, but it definitely renders if you ref it in your markdown. 🤷