kitql VS magidoc

Check out the repo: https://github.com/jycouet/kitql

Repository

This year, I've had to get rapidly up-to-speed with GraphQL. I thought I'd be starting from nothing, but I'd forgotten that TinaCMS (the headless content management system that I use with this site) uses it. One of the first problems I had to solve was how to generate static documentation. My limited research led me to two possible solutions: SpectaQL, developed from the earlier DociQL, and Magidoc. The latter has built-in search, so that made my choice for me. I use Hugo as my static site generator, so the first thing I had to do was start the local version of TinaCMS from my site's Git repository:

I was recently asked for my favorite resources and best practices for writing clear and structured API docs. I've developed my own style for writing API docs, but up until now I haven't published it. Although I've mainly worked with REST APIs, this guidance applies equally to GraphQL and any other APIs. But before I get to writing style, the most important requirement for good API docs is a good API. If you're using REST, validate it with Stoplight. If endpoints are inconsistent in how they handle common parameters, there's no way to write around the problem. This seems to be more of an issue with REST and may account for the move away from REST toward GraphQL. The next thing that you need is static, searchable docs. Don't expect your GraphQL users to find the information they need by browsing your schema in Apollo. Don't expect your REST users to scroll to the bottom of the Swagger UI page to find out how to format data for a given endpoint. If you need a no-budget solution, Redocly CLI and Magidoc are good places to start for REST and GraphQL respectively. Unless you use AWS hosting (which doesn't play nicely with Magidoc's clean URLs). And don't think that you're done when you've published your schema. Developers need workflows, code examples and reference information to understand how they are expected to use your API. Ideally, this information should live in a public developer portal. Your rivals are not going to be able to clone your product by examining your API. And even if they start adding features based on it, you'll always be several steps ahead.

Magidoc is a fully-free open source static documentation generator for GraphQL. Whether you want to get visibility on internal APIs or document public endpoints for your customers, Magidoc can do it all! If you're interested in learning more, come see our repo!

Indexing code

It depends on what you're trying to do with your blog. In Magidoc, this engine is used to take external markdown (provided by files or a GraphQL schema for instance) and convert it to html to build a static website. This kind of library is more adapted for this kind of use-case where the markdown is provided externally.

I'm asking because have an issue in my project in which I would like to implement such search. It is a relatively complicated feature, and one of the main thing is that I would like the site to be pre-indexed. Which means that the index should be created at build time, and not when you open the page. Is it what you did in your project?

Repo: https://github.com/magidoc-org/magidoc/tree/main/packages/starters/carbon-multi-page

Depends what you are looking to do with the documentation, but there are a few tools to generate static documentation. I personally built an open source tool to generate GraphQL documentation that we use in my company. It's called Magidoc, you can see the repo here, .

Building a templates means that you are free to choose the design of the website, but also that you can implement the template in Svelte! There is a contributing guide to help you get started with the project.