# Elm Example Publisher
**URL:** https://discourse.elm-lang.org/t/elm-example-publisher/5971
**Category:** Show and Tell
**Created:** [June 26, 2020, 10:14am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971 "2020-06-26T10:14:18Z")
**Posts on this page:** 9
**Page:** 1
### Author:  [@gampleman](https://discourse.elm-lang.org/u/gampleman)
#### Post date: [June 26, 2020, 10:14am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/1 "2020-06-26T10:14:19Z")
Today I would like to show you a tool I’ve been working on and using for a long time, but have finally taken some time to polishing enough to make it more widely used.
The Elm Packages Website is very good for API documentation, but doesn’t provide other forms of documentation. One kind, namely **didactical examples** , are often needed by some packages. For example graphics packages often work a bit like this:
Or in other words many packages work by giving you the pieces, but it’s up to you to assemble something useful out of them. Authors of these packages typically solve this problem by providing a directory of example programs, so you can learn some common patterns and see how the pieces fit together in something that is a bit realistic, but avoids much of the incidental complexity of a real app (so something like a step 1.5 in the above meme). However, a directory in GitHub makes it a bit hard to see the output of the examples without running them. Also as the number of examples grow, it can become hard to identify quickly which examples may be relevant to ones use case.
[Elm-visualization](https://github.com/gampleman/elm-visualization) has been tackling these problems for a few years now. The tool I’ve been using for this is called [elm-example-publisher](https://github.com/gampleman/elm-example-publisher). It takes a [directory of sample programs](https://github.com/gampleman/elm-visualization/tree/master/examples) and turns it into an [attractive website](https://5ef5b9b6eab87934b7e0ad41--elm-visualization.netlify.app).
This website is [written in Elm](https://github.com/gampleman/elm-visualization/blob/0ed565a5374c33eebf8863082771be0bcfabb89d/docs/Docs.elm) and can have some interesting features:
- Examples run on the page as well as showing their source.
- The index shows each example with a screenshot, allowing a user to visually identify examples that seem relevant.
- Examples have an Edit on Ellie link to quickly play with the examples (in the [demo website](https://5ef5b9b6eab87934b7e0ad41--elm-visualization.netlify.app) some of these are slightly broken, but that is due to not being built from a release tag)
There are some interesting technical features as well:
- The website is completely static (and apart from the examples themselves) runs even without JS
- It works great with [Netlify](https://www.netlify.com) for building and hosting in the Cloud
- The build system is flexible enough to support other documentations styles like [categories](https://deploy-preview-95--elm-visualization.netlify.app), tags, or even non-visual examples
If this sounds interesting, please check out the [README](https://github.com/gampleman/elm-example-publisher#elm-example-publisher) and give the tool a shot.
---
### Author:  [@DullBananas](https://discourse.elm-lang.org/u/DullBananas)
#### Post date: [June 26, 2020, 3:30pm UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/2 "2020-06-26T15:30:45Z")
no swear words please
---
### Author:  [@asteroidb612](https://discourse.elm-lang.org/u/asteroidb612)
#### Post date: [June 28, 2020, 8:34pm UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/3 "2020-06-28T20:34:12Z")
I think this is great! When learning some of elm’s larger packages ([terezka](https://github.com/terezka)/ **[line-charts](https://github.com/terezka/line-charts)**, [ianmackenzie](https://github.com/ianmackenzie)/ **[elm-3d-scene](https://github.com/ianmackenzie/elm-3d-scene)**, [mdgriffith](https://github.com/mdgriffith)/ **[elm-animator](https://github.com/mdgriffith/elm-animator)**, and your elm-visualization of course!) I’ve found the examples were the most helpful resource by far. And while those post examples in their own ways, I expect tools like this to lower the friction towards nice examples will be great for the ecosystem.
---
### Author:  [@alexkorban](https://discourse.elm-lang.org/u/alexkorban)
#### Post date: [July 2, 2020, 1:50am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/4 "2020-07-02T01:50:32Z")
Interesting! I have a very similar scenario for my [elm-ui-patterns](https://korban.net/elm/elm-ui-patterns/) site, but it never occurred to me that the implementation could be turned into something reusable.
---
### Author:  [@luke](https://discourse.elm-lang.org/u/luke)
#### Post date: [July 2, 2020, 5:12am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/5 "2020-07-02T05:12:37Z")
If you want to simplify the Ellie code, there’s a little-known feature where you can prefill a new Ellie without having to save
[https://ellie-app.com/a/example/v1?title=hello%20world&elmcode=hello&htmlcode=world&packages=elm%2Fbrowser%401.0.2&elmversion=0.19.0](https://ellie-app.com/a/example/v1?title=hello%20world&elmcode=hello&htmlcode=world&packages=elm%2Fbrowser%401.0.2&elmversion=0.19.0)
We added the feature for this exact purpose!
(Small thing - the percent decoder doesn’t handle `+` correctly so you have to use `%20` for spaces)
---
### Author:  [@gampleman](https://discourse.elm-lang.org/u/gampleman)
#### Post date: [July 2, 2020, 7:56am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/6 "2020-07-02T07:56:33Z")
Oh that’s cool, I was looking for something like that but [couldn’t find anything](https://github.com/ellie-app/ellie/issues/63), so I decided to reverse engineer how Ellie works. There is a nice GraphQL api behind it which was easy enough to repurpose for this.
The only thing I would slightly worry about for longer examples is URL length limits…
---
### Author:  [@Brendan](https://discourse.elm-lang.org/u/Brendan)
#### Post date: [July 9, 2020, 1:37am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/7 "2020-07-09T01:37:54Z")
This is such a great idea, I hope it catches on.
One small suggestion - if there’s a way to list dependencies for each example, that would be great! I know they’re all listed in the example directory’s elm.json, but even so it’s not evident what modules they expose from their names, especially when there are many packages in the list.
For example, it took me ages to figure out where Html.Events.Extra.Mouse was coming from when I was trying to use one of the elm-visualization examples.
---
### Author:  [@gampleman](https://discourse.elm-lang.org/u/gampleman)
#### Post date: [July 9, 2020, 7:41am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/8 "2020-07-09T07:41:18Z")
That would be really cool. I think there could be more done for the example source code in general. I often find I would like to check the docs of some function when reading the example code, but I have to search in a separate window.
---
### Author:  [@system](https://discourse.elm-lang.org/u/system)
#### Post date: [July 19, 2020, 7:41am UTC](https://discourse.elm-lang.org/t/elm-example-publisher/5971/9 "2020-07-19T07:41:20Z")
This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.