
Slate, create beautiful, responsive API documentation - wiradikusuma
https://github.com/slatedocs/slate
======
Hitton
I like the way it looks, and the fact it more or less works even without
javascript enabled is nice bonus, many other similar documentation solutions
can't do that. I'm torn about whole documentation being in one page, it
certainly makes it easier to Ctrl+F, but it's also easier to get lost.

But it has still some bugs to work on. I tried opening Travis CI documentation
to see it in action. When reaching [0], I wanted to scroll back up. Using
Firefox 79, I wasn't able to go up no matter what. When using Chromium 84, I
managed to go up when scrolling fast, but when holding up key, I still stayed
in place.

[0]: [https://docs.travis-ci.com/api/#linting](https://docs.travis-
ci.com/api/#linting)

------
twodave
I reviewed Slate for one of my clients' private APIs. We ended up using
Postman's API docs instead. The logic that brought us to that point were:

1\. The ability to generate/sync documentation from a Postman collection meant
we could write our test suite and documentation in one step.

2\. Since we were already paying for a team account, adding Postman
documentation was practically free.

3\. Environment variables. We could write our test suite with one set
internally and then publish our API docs with another set.

As someone else pointed out, it's possible to generate Slate documentation
from an OpenAPI spec, but to me Slate on its own leaves a lot to be desired.

~~~
karussell
Can elaborate what you need exactly and what Slate does not offer?

~~~
twodave
Honestly, like all decisions, there were many factors. A big hurdle in this
instance was that the existing application was written using a PHP framework
that made generating something like a SwaggerDoc an extreme pain. Since we
knew we'd have to write documentation outside the product anyway, and we were
already using Postman for tests, using their (free, and already hosted
someplace) docs was a no-brainer. It even allowed us to share the docs with
3rd party developers in a way where they could import the docs locally and run
them -- again, via Postman in order to test their own uses of our API (simply
by setting up a few variables like putting in their API key).

------
waf
I've used this before (as an API consumer, not an author), and while it's
better than many other documentation sites, for some reason the "scrolling
will change the URL and active navigation item" was really disorienting. I
kept finding myself lost in the one long stream of documentation -- there was
no anchor!

The goal is to have everything browser-searchable (i.e. ctrl-f), and I think
it's a good goal. I wonder if there's a better way than having everything on a
single page with very little compartmentalization, though.

~~~
throwanem
Since it's a static site, splitting the content across multiple pages and
still being searchable would mean you'd need to push the whole search index
down to the client and have the search operate locally. Not that it couldn't
be done, and I can think of a few optimizations, but for the "very large docs"
use case that's called out in the readme, it might still amount to a lot of
data _on top of_ the "a lot of data" that constitutes the docs themselves as
rendered. Relying on browsers' built-in text search makes a lot of sense,
especially to start with; I'd likewise wait to see a very strong use case
before building out my own search to supersede it.

I don't know how I feel about the way they're managing the URL fragment. The
way they're calling pushState, it adds history entries while scrolling, and
that makes the back button behave nonintuitively; I think I'd rather see
history entries created only when I click a header, or otherwise take some
specific action to demonstrate the intent. That makes the back behavior easier
to reason about, and also preserves the easy deep linkability that they are,
imo rightly, going for.

~~~
Aeolun
If you load all the content from the start, you also push the entire index to
the client.

It could even be faster because all the HTML markup can be left out for the
search index.

~~~
throwanem
If you do it as separate static pages, though (per the upstream comment: "I
wonder if there's a better way than having everything on a single page with
very little compartmentalization...") then you're no longer pushing all the
content to the client at once. That limits the scope of the browser's built-in
search to the current page, and thus necessitates the additional complexity to
regain support for searching over all the docs.

------
karussell
Thanks for posting that. What I like about slate is that it seems to be
searchable via Ctrl+F which makes it an advantage over ReDoc where search is
broken IMO.

We are currently reviewing several API doc creators including commercial once.
And none of them seems to have the feature that I can perma link to a certain
request (or response) parameter. E.g. /api1#some/nested/parameter. This seems
to me very useful as we don't have to copy the description and type of the
parameter again.

You see what I mean when you go to the slate example page
[https://slatedocs.github.io/slate](https://slatedocs.github.io/slate) and
search e.g. "available" then you click on the result and you will be directed
to the "Get All Kittens" instead of the parameter directly which is confusing
if you have more than a few parameters and you have to scroll down. I.e.
Ctrl+F is better than this Search feature.

The same problem exists for ReDoc. We tried to contribute a change that
supports this perma link feature, but it was not even reviewed.

Any recommendations?

------
btown
As much as I love the _idea_ of a single page, I've seen massive Slate docs
where time-to-interactive is 10 seconds or more because even a modern browser
on a modern machine struggles to layout such massive volume of docs.

See, for instance, Spreedly's documentation - an incredible service btw for
future-proofing your payments stack and allowing PCI-compliant routing to
practically any payment processor. (Not affiliated, just a happy customer!)
The only time I'm not a happy customer, though, is when I'm time-constrained
and have to load the docs, because this is their Lighthouse report:

[https://lighthouse-dot-
webdotdevsite.appspot.com//lh/html?ur...](https://lighthouse-dot-
webdotdevsite.appspot.com//lh/html?url=https%3A%2F%2Fdocs.spreedly.com%2Freference%2Fapi%2Fv1%2F)

> Performance score 8/100, first contentful paint 9.5s, TTI 16.1s, 5s for
> style & layout, 3.5s for rendering, 43k DOM elements

All that said, Slate is really great. I'm certainly not asking for Spreedly or
anyone else to switch tech for their docs. The benefits outweigh the costs.

And I get that you can't have gradually-laid-out content and also preserve
scroll position on refresh in a responsive environment. Theoretically, you
could, but you'd need to exactly measure your text size at dozens of
responsive breakpoints and pre-set each section's height, which would require
a headless browser as part of the compile pipeline. And the last thing we
want, _especially this week,_ is advocating for documentation sites to take
_longer_ to compile. So perhaps this is the local optimum. But hopefully there
are other more creative solutions!

~~~
baddox
That is an absolute monster of a page, and while the JS is slow, that's not
even where the problems begin. This thing is _1.5 MB of HTML_ , which takes
3-4 seconds just to download on my gigabit connection (it doesn't appear to
support compression, which might help a lot).

~~~
btown
Compression wouldn’t help the 8.5 seconds spent on layout and rendering of the
text.

------
roopakv
I've seen Slate. I know CircleCI uses them. Personally however I am a huge fan
of redoc. Something about the way redoc looks and the way it is served makes
me want to pick them over slate.

[https://github.com/Redocly/redoc](https://github.com/Redocly/redoc)

I've managed to get both the companies I work at use redoc instead of slate :)

------
ForHackernews
Can this be generated from an OpenAPI3 spec?

~~~
RileyJames
This seems to be the most supported project to convert OpenAPIv3 + other docs
specs to a Slate compatible format.

[https://github.com/Mermade/widdershins](https://github.com/Mermade/widdershins)

~~~
gwittel
I’ve used this with the CLI wrapped version that’s linked to in the readme and
it works well enough. There are shins bugs/gaps in the template where some
OpenApi fields are not rendered though.

In the end I containerized the whole thing with defaults, logos, etc so we’d
have standard docs with little effort.

------
BrandiATMuhkuh
While I like how it feels and look, I really miss being able to have a try
button. Like on swagger, I want to add test data and try it. This is one of my
favourite features when I explore APIs of other companies.

------
hirundo
I'd love to be able to generate Slate docs for a GraphQL API from an
introspection query.

~~~
noisy_boy
Me too. Having used Altair/GraphQL Playground/GraphiQL, there is a lot that
can be done in the automatic doc generation/ interactive query space. E.g. it
would be very useful to see a schema/ER diagram like visual representation
driven by introspection.

------
sandGorgon
is there anything like this but in pure javascript/typescript ?

ideally a SSG like Gatsbyjs or Nextjs

~~~
ksajadi
Something like
[https://github.com/facebook/docusaurus](https://github.com/facebook/docusaurus)

