Our great sponsors
-
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
markdown-it
Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed
-
eleventy 🕚⚡️
A simpler site generator. Transforms a directory of templates (of varying types) into HTML.
-
-
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
-
-
The outcome I was (mostly) hoping for has been done by Shiki library! I take no credit for the idea btw, I am just glad that someone else (Pine) took it on!
Rodrigo Pombo is the creator of Code Hike. He has been making tools to make code and technical data more comprehensible for some time. Previously, he applied a similar technique to make your git history easier to navigate and comprehend with git-history.
At its core it is an extension to the popular open-source Markdown library markdown-it. Plugins for markdown parsers and preprocesseors are an avenue for more innovation of this nature.
For example, with the eleventy (11ty) static site generator, you can use use many different template languages to create webpages. The explanations in the docs demonstrate concepts using the 4 most popular template choices in a tabbed pane, as below.
A pioneer in technical documentation is Stripe. Their docs have exemplary code walkthroughs. Stripe are smart to recognize this as an opportunity. Their core audience is developers. Any friction they can remove to make it easier for devs to understand their SDK and APIs will boost adoption of their product. And that should boost their revenue. 🤑
Nowadays, the most common source of visual essays is from the data visualization (data viz) community. Publications such as The Pudding cover a varierty of subjects. However, the subject matter is not web development. But in order to produce the visual essays, the writers must know web development, right? Well, why don't they turn their attention to explaining web development topics in a similar way, wouldn't that be great?
If you want to use a libary in the browser, a lightweight library like Prism is more suitable.
There is a rise in markdown-based formats to bring capacity for integrating interactive content into documents, namely using web components in markdown. MDX enables using JSX with markdown, the chief aim to bring React components to markdown. Mdsvex brings svelte components to markdown.
It is interesting to analyse Stripe's moves in this area. They created their own Markdown-based document format called Markdoc. This was designed to meet the needs of their user-facing product documentation. They said the following on why they created Markdoc:
The Astro framework takes this further in their docs, by coordinating the selection of their tabbed instances in the same page. For example, in the guide on Integrations, they have instructions on how to add the correct packages for the integrations. They have a tabbed view with a tab for each of the most popular package managers: npm, pnpm, and yarn. Selecting 'pnpm' in the first instance, switches the active tab to 'pnpm' for all tabbed instances in the page.