eleventy icon indicating copy to clipboard operation
eleventy copied to clipboard

Published 20 hours ago • verified publisher icon 11ty

Provide API docs and specify public API

Open chriskrycho opened this issue 5 years ago • 4 comments

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

chriskrycho avatar Dec 07 '19 15:12 chriskrycho

This is even more important now with Eleventy Serverless.

zachleat avatar Jul 28 '21 14:07 zachleat

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

zachleat avatar Jul 29 '21 13:07 zachleat

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

Also Related:

  • https://github.com/11ty/eleventy/issues/814
  • https://github.com/11ty/eleventy/issues/2033

panoply avatar May 15 '22 05:05 panoply

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

zachleat avatar Jul 01 '22 21:07 zachleat