[Discussion] Mithril Community Blog - ideas and implementation details

[orbitbot]

The starting point

In relatively recent gitter chatter an idea was floated to implement a community blog for Mithril, to serve as a way to present good practices, ideas, guides and related content in a less formal fashion than part of the official documentation. One motivation for maintaining a blog is that from user anecdotes it's been clear that Leo's original blog posts have been a driving force in gaining interest in Mithril.js in the first place, and perhaps a place to collect similar thoughts could serve a similar purpose and demonstrate the utility that this framework provides.

The reason to maintain a blog as a community initiative is to remove the maintenance and content generation burden from individual people, while allowing for a breadth of viewpoints and practices to be presented.

Suggested content

Some initial thoughts on what would serve as good content for blog posts:

• guides around FAQ content on the gitter chat
• updated takes on Leo’s original blog posts, with more recent (1.x …) APIs
• how to combine mithril with , eg. replacing the js from that framework
• common patterns in other frameworks that require a boatload of dependencies that are relatively straightforward to achieve
• hyped implementations that are more or less trivial to implement with a few lines (see styled components with bss, ...)

... further suggestions welcome, in no way are the above to be considered exhaustive

Breakdown

From the current starting point, there are multiple things to consider, roughly divided into 1) design changes 2) automation and 3) process for content production.

1) Design

Leading question: "What does the end result look like?"

The blog posts should be hosted on the Mithril.js website, and automatically generated like the rest of the website. The website already provides for a reasonable look that can be extended to present blog post data with some changes;

• add a Blog section to the top-level navigation (Guide | API | Chat | Github)
• add a index.html for the blog section, served at either https://mithril.js.org/blog.html or https://mithril.js.org/blog/, whichever is easier to implement
  • blog index contains a blurb & disclaimer about "why mithril blog", see motivation at the top of this Issue
  • blog index contains a blog archive of the available posts in reverse chronological order below the introduction

... Additionally, for each blog post, a separately linkable page with a permanent URL, that

• contain posts generated from individual markdown files like the rest of the website, that
• display when post was written
• display author details of blog post writer
  • name or nickname (github username?)
  • gravatar
  • short (< 200 chars) description (“bio”)
  • social media links (gh profile, twitter, … )

Some minor changes in site CSS is probably required to accommodate a uniform look.

2) Automation

Based on the design target and any adjustments, a blog subfolder should be created, the content of which is individual blog posts, and supplemental files to automatically generate the blog section and posts whenever the website is rebuilt, similarly to the docs folder and the existing website.

• generate blog HTML from markdown files with deterministic URLs and content
• autogenerate a blog archive from the available posts in reverse chronological order below the blurb in the blog index (any way to reliably add timestamps to these links?)

3) Process

With the above in place, there should be an toolchain easy enough to use for any potential authors to create content. Then begins the process of collecting enough content and maintaining some level of quality for the blog to actually provide meaningful content. To that end, posting frequency should aim to be somewhat constant at a reasonable pace, say a target for 0-2 posts / month with a minimum of 10 posts a year (once or twice a month outside of summertime?). This will of course be guided by how easy it is to find proper content and how eager the actual writers are for providing content.

My assumption is that it could/should be enough to try to collect authors from the gitter chat based on discussion topics there, assuming someone has the presence of mind to highlight that a subject might be well presented in a blog form.

To generate some order for writing/posting, potential authors are requested to submit a title and a one-sentence/paragraph synopsis for their potential posts, and the community shall use <polling website> to vote on the most interesting topics. After being tasked with completing the post, an author should aim to complete the post in a reasonable timeframe (say around 2 weeks). Finished posts are submitted as normal pull requests to the new blog subfolder.

Open items

1. where to place author data on a blog post page? alternatives are likely

• sidebar
• header, eg. section before blog body text
• footer, section after blog body text

2. how to maintain blog metadata deterministically, marked does not support blog metadata? (parsed html comment?)
3. does blog post pages have sidebar links like the current pages?
4. does “the process” (go philly?) make sense, or should content generation be organised in some other fashion?

A preliminar flems outlining what a blog post might end up looking like can be found here. Using flems as a blog writing tool with a preview can also be achieved without too much effort, though note that most of the mithril.js.org website generating tweaks (automatic subsection linking etc.) is not in place.

Thoughts and comments welcome :)

[dead-claudia]

I would personally prefer blogs to be done out-of-repo (linking to them is okay), but the way those Gitter discussions have been going on, I feel this particular idea could be better done as a new section under "Tutorials", where we could maintain it as a community. Rust already does kind of similar with their book, although I'm not advocating that particular solution.

---

I do strongly agree we need a good tutorial that can onboard people very quickly and that we can easily point people to.

[kylebakerio]

I do like this idea. I would definitely spend time perusing such a blog.

While of course it seems a bit silly to run a blog on mithril in a non-mithril environment, it is painfully easy to set up a hexo blog. And given that there isn't much movement here, I'd suggest it might be worth setting that up to start with as a separate repo, and letting that be what we use until contributors are irritated by that enough to develop a proper blog platform, if ever.

In the end, it might even be possible to stick with hexo and just write a custom theme using mithril... I've never written one myself, so I can't say how much hacking it would require to get it to not generate multiple individual pages, unfortunately.

I don't love the idea, it would break with the aesthetics and certainly stand alone, etc.--but it's better than the blog just never getting around to happening. ¯\_(ツ)_/¯

[dead-claudia]

Related: #2262

[barneycarroll]

Closing #2262 in favour of this.

@spacejack suggests as subjects for posts:

• Re-using event handler functions in closure components
• Using your POJO/class component as an EventListener object

Other things that come to mind:

• Avoiding stale attrs
• Using callbacks or streams to update parent data
• Technique to pass a "querystring" (optional params) in a url
• Ways to force compnent re-init on route change (where the component would otherwise persist)
• Sending a function as children (this is your trick Barney - there's better support in V2 now isn't there?)
• Using children or render functions in attrs
• Example of a canvas component that redraws on attr changes (show an example of implementing your own attrs diff)
• Nuances of using await m.request(). Maybe show an example using promises to defer the redraw until a chain of async operations resolves.
• How to handle error statuses from m.request()
• Explain the difference between running an auto-invoked css animation vs a transition, and why you have to first "force render by reading from the DOM" to trigger the latter in oncreate.

@orbitbot highly relevant at the moment:

• common patterns in other frameworks that require a boatload of dependencies that are relatively straightforward to achieve
• hyped implementations that are more or less trivial to implement with a few lines (see styled components with bss, ...)

Got a great post stewing away in my mind under the title Out of context ;P

[StephanHoyer]

hooks with mithril 🙈

[spacejack]

Sorry I wanted to comment on this earlier but got too busy this week. Re:

It might sound silly, but I think this would make most sense as a separate repo (perhaps to be pulled in as part of the site build).

Actually, I think this should be on the main TOC for the site (maybe a new section under "Key Concepts") and that the API docs should link to it when appropriate.

I didn't feel this should take the place of the old blog exactly. A blog allows you to discuss a lot of things, in depth, and even offer opinions. These seemed more like a shorter series of technical explanations and how-tos that are as unopinionated as possible; basically just extended documentation that doesn't feel comfortable getting crammed into the API docs.

I also thought that all of these topics could fit on one page. More lengthy discussions (e.g., about architecture) would be good candidates for a blog. There is probably a grey area between the two but I think the topics I suggested can mostly be covered within a few paragraphs and a couple of code snippets each.

IMO good blog candidates would be:

• common patterns in other frameworks that require a boatload of dependencies that are relatively straightforward to achieve
• hyped implementations that are more or less trivial to implement with a few lines (see styled components with bss, ...)

[spacejack]

Uh, I'm going to walk that claim back a bit on the length of the posts... I've started drafting one about events and it's longer than I thought, heh. :)

Anyway I'm going to try sketching out a few of my suggested topics above in this repo for now.

[dead-claudia]

Related: #1929.

[spacejack]

A recent gitter thread has reminded us that more animation examples would probably be very beneficial. Showing simple vanilla/mithril examples of 3rd party components for other libraries might help people who are trying to decide on a framework. They also make for great showpieces for a library.