search

11ty / eleventy

A simpler site generator. Transforms a directory of templates (of varying types) into HTML.
https://www.11ty.dev/
MIT License
16.91k stars 491 forks source link

Provide API docs and specify public API #814

Open chriskrycho opened 4 years ago

chriskrycho commented 4 years ago

Is your feature request related to a problem? Please describe.

Right now, there are two major limitations to Eleventy's API documentation:

  1. Information on the APIs is scattered throughout guide material, making it difficult to find all the capabilities of the tool.
  2. There is no single source of truth for what constitutes the public API of the project, i.e. what is safe to rely on and what is not.

This makes it difficult to know what parts of the existing implementation are safe to use and which aren't. It also has made it difficult to build accurate TypeScript type definitions for the project.

(Not everyone wants to use TypeScript, of course, and that's totally fine! For those who do want to use TS, though this is really important—and even for those who don't, it can really improve the dev experience for writing plain-old JavaScript. Anything which uses the TS language server, especially VS Code but equally something like Vim, can get benefits from this!)

Describe the solution you'd like

It would be great if Eleventy included dedicated API docs which specified the public API of the project, separate from the guides material. The guides are genuinely fabulous, but they constitute a different kind of docs than exhaustive API docs do. (As a point of reference, consider this great writeup of different kinds of documentation!)

Describe alternatives you've considered

The obvious alternative is to do nothing: leave the API documentation only available in the guides. This is definitely less work!

Additional context

An example of how this can improve dev experience:

Screen Shot 2019-12-07 at 08 05 42
zachleat commented 3 years ago

This is even more important now with Eleventy Serverless.

zachleat commented 3 years ago

Oh one more comment here, I do want to make sure that this is published on the web site and not included in the bundle, for bundle size reasons https://github.com/11ty/eleventy/issues/1885

panoply commented 2 years ago

See - https://github.com/11ty/eleventy/issues/577#issuecomment-1126862063

Also Related:

zachleat commented 2 years ago

Just for completeness I’d link up a very minimal page here https://www.11ty.dev/docs/programmatic/