Custom markdown editor

[rviscomi]

This year I've heard of a few content teams struggle to get their Docs draft converted into markdown for publishing. That's got me thinking about ways to streamline the process and one idea is to have a custom editor for authors to write in markdown format and preview how it would look. It would effectively be an interactive web app version of our watch/generate build scripts.

The author workflow would be to iteratively write and preview in the editor and save the markdown contents to a git branch. This can be a lightweight replacement for authors who may not be comfortable setting up their own local development environment.

As long as I'm daydreaming about features, what about a few stretch goals:

• authors authenticated with the GitHub API can automatically save changes to a branch
• coauthors can collaborate on the same branch in real-time
• a library of markdown blocks for common use cases (tabular figures, asides, big numbers, etc)
• paste/upload images and save them to the chapter's img directory in the branch
• authenticated reviewers can leave inline comments on the rendered HTML
• figures rendered into HTML from the Jinja syntax
• in-editor linter warnings and build errors, eg "This figure is missing an accessible description!"

The idea was inspired in part by the GitHub and dev.to content editors. Edit in markdown and click the "Preview" button to see how it would appear when published.

Do I need sleep or am I onto something? Both?

[hemanth]

I had a similar thought, I think we should go for it, having highlight and comment and reply on comments and a chat area would be good to have too.

Also, it would be nice to have an area where we can generate the required graphs too? (So, everything is under one hood)

[tunetheweb]

OK so all we're looking for really is a simple to install, lightweight, cross-platform program with the power of Chrome, Visual Studio Code, Slack, and GitHub Desktop with an in-built node and python interpreter that allows running of Flask/Jinja2?

I think you may need a little sleep there all right! 😁

The much better option IMHO is to just install Docker and run one command to have the environment up and running with a file watcher. So you can use Chrome, Visual Studio Code and Slack for real! I know of at least one Author who did this (@dotjs) who produced a very high quality conversion without any guidance other than the wikis. Granted he's technical, but think that's the best way.

Also, it would be nice to have an area where we can generate the required graphs too? (So, everything is under one hood)

This is something I think we can improve on. We made it a LOT easier this year (believe it or not!) but think there's more we can do here - particularly for exporting the fallback images.

[rviscomi]

OK so all we're looking for really is a simple to install, lightweight, cross-platform program with the power of Chrome, Visual Studio Code, Slack, and GitHub Desktop with an in-built node and python interpreter that allows running of Flask/Jinja2?

I think you may need a little sleep there all right! 😁

Well when you put it like that! ;)

For an MVP, I think an app that only shows how the markdown would be rendered (Edit/Preview) will go a long way. All of the wishlist items are nice to have in an integrated way, but they add complexity and we already have functioning workflows to handle them.

I was thinking that the MVP wouldn't be too unreasonable because we seem to have all of the pieces already. I'd imagine this working in two parts: an API and a frontend editor. The API takes markdown, runs our build pipeline, and outputs HTML. The editor would be a textarea with a preview mode that calls the API and renders it on a mockup of the chapter.html page.

I'm wary of a "just install Docker" solution, which could be a high barrier to entry for some.

Also, it would be nice to have an area where we can generate the required graphs too? (So, everything is under one hood)

This is something I think we can improve on. We made it a LOT easier this year (believe it or not!) but think there's more we can do here - particularly for exporting the fallback images.

+1. The original dream (if I can find the old issue) was to have a process that runs analysts' raw SQL, saves as JSON, and a syntax for authors to summon data viz (eg {{ bar_chart(metric="flexbox_adoption", ...) }} or {{ data_table(metric="h2_server_push", columns=["server", "push_enabled"]) }}) which would generate responsive HTML/SVG charts and eliminate the need for Sheets and fallback images. Maybe in Web Almanac 2025 😆