This a rewrite of the website completely from scratch. The old website is written with Docsify, a JavaScript plugin to live convert Markdown to HTML. This is a very laborious process to update, difficult to verify, and quickly goes stale and incorrect.
The proposal is to rewrite the documentation into a OpenAPI Specification (OAS, or just spec), which is a both machine- and human-readable data format. By instead defining the API in YAML it allows us to easier validate and keep the spec up-to-date. We can then use spec to automatically generate Markdown or pretty HTML documentation with tools like Rapidoc or Swagger. It also allows automatic SDK generation in countless of languages. This has already been completed in the separate repository specification.
Changes
This PR therefore proposes to replace the Docsify page with a website that directly uses the API specification itself for documentation. This means when any update is made in the specification repo it would automatically update on the website, and that this repository instead would contain the graphical resources and HTML for the display.
✨ Preview: See Cloudflare Pages reply below
This website is made with Jekyll for templating and uses Rapidoc for rendering the spec. It also adds better support for writing tutorials, and specific pages for each language SDK. The information about each SDK is fetched from GitHub's API with the download-data.js, which would be set to run periodically.
The website can be built locally with:
bundle install
bundle exec jekyll serve
This will start a local web-server on http://localhost:4000.
The website has been designed with the goal of improved SEO and mobile-compatibility in mind. Redirects has also been created for all old pages to preserve links. The niche remaining missing information e.g. In-game Analytics and ResentConfirmationEmail will remain in the Git history and already have To-Do issues linked to them to be re-added to the new site, so old information will not die.
Feedback
Recommendations for something that should be fixed or any other kind of feedback is warmly appreciated!
Background
This a rewrite of the website completely from scratch. The old website is written with Docsify, a JavaScript plugin to live convert Markdown to HTML. This is a very laborious process to update, difficult to verify, and quickly goes stale and incorrect.
The proposal is to rewrite the documentation into a OpenAPI Specification (
OAS
, or justspec
), which is a both machine- and human-readable data format. By instead defining the API in YAML it allows us to easier validate and keep the spec up-to-date. We can then use spec to automatically generate Markdown or pretty HTML documentation with tools like Rapidoc or Swagger. It also allows automatic SDK generation in countless of languages. This has already been completed in the separate repository specification.Changes
This PR therefore proposes to replace the Docsify page with a website that directly uses the API specification itself for documentation. This means when any update is made in the
specification
repo it would automatically update on the website, and that this repository instead would contain the graphical resources and HTML for the display.✨ Preview: See Cloudflare Pages reply below
This website is made with Jekyll for templating and uses Rapidoc for rendering the spec. It also adds better support for writing tutorials, and specific pages for each language SDK. The information about each SDK is fetched from GitHub's API with the
download-data.js
, which would be set to run periodically.The website can be built locally with:
This will start a local web-server on
http://localhost:4000
.The website has been designed with the goal of improved SEO and mobile-compatibility in mind. Redirects has also been created for all old pages to preserve links. The niche remaining missing information e.g. In-game Analytics and ResentConfirmationEmail will remain in the Git history and already have To-Do issues linked to them to be re-added to the new site, so old information will not die.
Feedback
Recommendations for something that should be fixed or any other kind of feedback is warmly appreciated!
Screenshots
Advanced search functionality:
Picture of Phone 1
Picture of Phone 2
Fixes #72, fixes #73, fixes #80 due to already being fixed in spec, or have separate issue there.