Elm-doc-preview: A new online documentation previewer

Show and Tell
1

I made an online Elm 0.19 package documentation previewer:

https://dmy.github.io/elm-doc-preview/

It can preview README.md and docs.json files (one of them or both of them simultaneously).
If you loaded both files, you can then update one of them without losing the other.

It is not yet perfect but hopefully it can already be useful. Feedback is welcome (here or in a github repository issue).

Notes:

  • 0.18 packages are not supported.
  • It is only an online service for now but I think that it would not be too hard to make it run locally, so if this is really important for you, tell me why and I will consider it (PRs are also welcome).
  • Why a cat? Because they see better than us in the dark.

Credits

  • Using elm/project-metadata-utils helped a lot, thank you @evancz :black_heart:
  • It uses a copy of the package.elm-lang.org CSS, so thank you again for making this freely available
26 Likes
2

Thank you for doing this. I was considering doing it myself. Now I don’t need to. Bookmarked.

2 Likes
3

Thank you very much for this. Previous to this, I had to use a hacky locally cloned version of the package website.

1 Like
4

Update:

1. Moved to Netlify

elm-doc-preview has moved to Netlify (mainly because Github Pages SPA routing is a hack, even more without a custom domain). This is the first time I test Netlify and for now I am impressed.

The new URL is: https://elm-doc-preview.netlify.com/

The previous URL is redirected so bookmarks/links should not break.

2. Previews should now be 100% identical to final documentation

After some thought, I now use the original viewer code from package.elm-lang.org, so the preview should be exactly identical to the official documentation.

Also the same URL scheme as package.elm-lang.org is now used, so links to types and functions are now supported.

3. Previews are now stored in local storage to support inter-modules markdown links

Previews are now stored in local storage (only the last README.md and docs.json loaded) to work around a limitation of elm-explorations/markdown that lead to page reloads when links inside markdown are clicked.

Consequently there is now a “Close Preview” link to close the preview and clear the local storage.

4. Drag & Drop

You can now drop README.md and docs.json files anywhere in the page at any time.

9 Likes
5

This is really useful and makes checking complex documentation much easier. I like the fact that it renders images as they appear on the official doc pages. Previously the Elm 0.18 doc preview would handle images larger than the 600px column width differently to the final version on the official published doc. This was the cause of too many patch releases for me until the published rendering worked as expected.

Thanks so much for putting in the time to do this.

1 Like
6

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.