Preview: Live Edit – Feedback wanted!

[squidfunk]

I just threw a POC together running the visual part of the Material for MkDocs stack in-browser. This would omit the need to install anything via pip or docker, as tech writers could just use the in-browser live editor to instantly preview their changes:

I'm astonished myself how fast this is. A live video showing the instantaneous rendering can be watched here: https://twitter.com/squidfunk/status/1338252230265360391

Any feedback is appreciated. Would you consider this useful? How would your ideal workflow look like?

[fveauvy]

I think this could be a killer feature for technical writers. Is this Git based ?

[Stephen-Gates]

Do you want feedback on the idea (awesome) or someone to test the proof of concept (I’m in)?

[squidfunk]

@fveauvy I think this could be a killer feature for technical writers. Is this Git based ?

It's currently a proof-of-concept I threw together in a few hours, so it's only running locally on Webpack dev server, showing an input field on the left and the rendering on the right, no git integration yet. However, it's definitely possible to pull-in files from git, edit them and commit them. That's a great idea and something I've already considered.

@Stephen-Gates Do you want feedback on the idea (awesome) or someone to test the proof of concept (I’m in)?

I first would really like to better understand how users currently work with MkDocs, i.e. what workflow you currently have and what your ideal workflow would be. Many people have trouble setting up Python or Docker, so what I would like to provide is an experience that is as frictionless as possible. This would not replace MkDocs, as it's only meant to preview the content area where your Markdown document goes, but it allows for a much better editing experience, as the reload cycle is not 4-5s but less than 100ms, so it's a huge time saver.

It already supports 90% of Python Markdown and Python Markdown Extensions (like tabs etc.), but there's still some work to be done. Two possible directions where this could help:

• A Visual Studio Code plugin, i.e. like Markdown Preview, but using Python markdown and rendering in Material's style. It could also pull in your extra CSS files and apply your changes / overrides.

• An in-browser solution, which pulls in the docs folder of your repository after a GitHub login and allows for editing and committing right from the browser.

The Visual Studio Code plugin is easier to implement, and could be a good first milestone, since VS Code already has a git integration etc. and has an awesome editing experience. We could also provide snippets for admonitions, tabs, etc. This would essentially free you from the need to run MkDocs. The in-browser solution could be good for on-the-go editing (like fixing typos etc.).

[Stephen-Gates]

Here's my layman's practice (some of this is from memory so may not be 100% accurate).

I use Insiders, additional CSS and JS (for sorting tables), MacOS Terminal, Atom with some Prose linters, GitHub Desktop, GitHub Pages.

• I create a repository on Github
• Clone to desktop
• Install with pip - I did have trouble with this.
• Create my site
• A: Edit MkDocs.yml and .md files
• $ MkDocs Serve. Read Warning to detect potential broken links
• Review site locally
• Goto A: and repeat until ready to publish
• If ready to publish MkDocs Build --clean
• delete a bunch of .html files that a lurking in various places - not sure why these aren't cleaned up by build.
• Use Github Desktop to upload files including /site
• Wait a bit for GitHub Pages to do its thing - Review pages online.
• Goto A: write some more and repeat.

I tried publishing with GitHub Actions but can't get that to work.

As for ideal workflow, I'll give that some thought and reply here.

[martinbira]

Similar to @Stephen-Gates. I myself write in Sublime, and my contributors (i.e. devs) use their own editing environment, Visual Code or Eclipse. We have our repo in GitLab where we create doc branches and where a Jenkins file create, update, delete, and publish dev sites when we push to the branches. When a branch is merged to master, the branch is deleted and we can publish from our master build to S3.

I have my own local installation of MkDocs/Material where are upgrades and customizations are tested and I have the MkDocs development server on at pretty much all times when writing. Some our my contributors skip that and work directly against GitLab and the dev sites. So for my contributors, this could be a nice feature, especially for those working with Visual Code.

[Stephen-Gates]

Some thoughts on ideal workflow without fully understanding VS Code + plug-in + Github integration possibilities...

• I create a repository on Github
• Clone to desktop
• Create my site - perhaps I could avoid terminal and do this manually or within VS Code?
• A: Edit MkDocs.yml and .md files
• Review site within VS Code preview
  • would linking between pages work within preview?
  • could I change the size of the preview to get a sense of the layout on mobile?
  • could the preview be shown in a separate window?
• Goto A: and repeat until ready to publish
• If ready to publish, do something in VS Code to upload to Github. Show warnings if there are broken links or other issues.
• Automatic site build on Github
• Wait a bit for GitHub Pages to do its thing - Review pages online.
• Goto A: write some more and repeat.

I work solo so don't deal with branches, multiple, and potentially clashing, contributions. Assume VS Code + Github integration can help with this.

[squidfunk]

Thanks for outlining your workflows!

would linking between pages work within preview?

Yes, that can definitely be implemented and makes a lot of sense.

could I change the size of the preview to get a sense of the layout on mobile?

If we render the preview in an iframe, the size of that iframe can be made adjustable. It's also something I already thought about which makes a lot of sense to provide.

could the preview be shown in a separate window?

Tiling is the easiest approach, as it can be done in a single session. a separate window would require for some communication across browser Windows. However, I'd like to keep the preview flexible, so it can be tiled vertically or horizontally, which is possible with editors out-of-the-box and should be quite straight forward to implement for a web-based solution.

[squidfunk]

I myself write in Sublime, and my contributors (i.e. devs) use their own editing environment, Visual Code or Eclipse. We have our repo in GitLab where we create doc branches and where a Jenkins file create, update, delete, and publish dev sites when we push to the branches. When a branch is merged to master, the branch is deleted and we can publish from our master build to S3.

If such a plugin for VS Code existed, would that be a reason for your users to switch from Sublime or Eclipse?

[facelessuser]

If such a plugin for VS Code existed, would that be a reason for your users to switch from Sublime or Eclipse?

I know I wouldn't switch to VSCode for such a plugin 😏. Editor preferences are very personal.

[martinbira]

If such a plugin for VS Code existed, would that be a reason for your users to switch from Sublime or Eclipse?

Not sure. It could get me to switch from Sublime, but our Java programmers probably won't leave Eclipse for that :)

[SaltyAimbOtter]

This would greatly improve our projects documentation workflow. The entry barrier for any new contributer is quite high currently as they need to install Python & an IDE etc. We have actually written it down: Our docs contributer page

Im personally fine with using these tool as I'm a developer myself but an even faster rendering time would still be amazing!

[tedyoung]

While I'll never leave my IntelliJ IDEA environment for Java, this would be great to have in VS Code (which I do use for some small JS/TS projects). For editing Markdown, etc., I'm less tied to a specific environment.

I currently have the Docker image running, but my workflow is write a bit, preview, fix something, preview, write a bit, etc., so not having even that 2-3s delay would be great.

[squidfunk]

Thank you @SaltyAimbOtter and @tedyoung – indeed the lowered barrier and shortened write & compile cycle are the main motivation for this solution. Providing a full-blown IDE in the browser might be out of scope at first, but boiling it down to three instructions for getting it working might already do the trick, i.e.:

1. Install VS Code
2. Install VS Code Extension
3. Open Markdown Preview

It could essentially be a supercharged version of Markdown Preview which is aware of mkdocs.yml and applies your customizations and configuration to the preview.

[x10an14]

@squidfunk: My/our workflow where I work:

1. Navigate into git-repo
2. Use poetry (read: pyproject.toml) to install mkdocs and theme(s)
3. Use poetry run mkdocs serve --strict for live editing

PS: I don't find any issue with using mkdocs with neither poetry nor pipenv. Besides this awesome suggestion of yours, the only other improvement I've thought of that I I would've liked to see would have been https://github.com/mkdocs/mkdocs/issues/2108. Thanks for awesome work!

[wilhelmer]

Oh my, a Material VS Code plugin would be a dream for us. We are working with five technical writers on a fairly large project that takes >5 mins per build, so neither mkdocs serve nor mkdocs build are an option for quick previewing.

So what we currently do is using mkdocs-exclude to build the project with selected topics only . I've created a VS Code task that takes an input string, puts it into the regex: directive, saves the modified mkdocs.yml as mkdocs.tmp, builds MkDocs with the temp file, and finally deletes the temp file. Quite a hack, but it saves so much time ...

Alternatively, we can build the entire project via Netlify, so at least it's not blocking our machines while building.

So obviously, a plugin would be much, much better than that, however, I'm not sure if would be really instantaneous for our project. Instead of generating the entire project (like mkdocs serve), it would need to render the current page only, it is that what you're thinking of?

[squidfunk]

Instead of generating the entire project (like mkdocs serve), it would need to render the current page only, it is that what you're thinking of?

Exactly. It would be something like a supercharged Markdown Preview, i.e. for getting a preview of the current page. It will never replace MkDocs as a build system, so it won't show navigation or other parts of the theme - only the content area. This is solely meant to make the write & preview cycle as fast as possible.

At the beginning it will only support stock Material styles. Later, it can pull in information from mkdocs.yml to apply customizations (extra CSS and maybe JS), and configuration values (primary and accent colors, extra icons, etc...) It may never support all of Material for MkDocs, but it could be a 95% good enough solution that takes a lot of pain away.

[Guts]

Hi there!

This seems to be a killer feature! Especially the in-browser option :heart_eyes:.

To explain why: we use it for a collaborative website (blog and collegial content). Here is our actual workflow:

1. a branch is created with the new content file
2. a PR to master is created with some checks (mkdocs build --strict, markdownlint-cli...)
3. every contributor writes his prose using whatever he wants as long as it's markdown at the end ;)
4. once the final content is ready to be published, the PR is merged into master (which is protected)
5. every commit on master triggers a deployment to the relevant GH Pages

The goal being to encourage an easy but quality contribution, it is difficult to ask end-editors (who are not all technical) to use IDEs (Visual Studio Code, Atom...) or even online editors (stackedit, hedgedoc...) that do not take into account the specificities of Python Markdown and even less mkdocs and customizations, first of all the theme.

I had a similar idea a few months ago and I started from a live editor based on a minimalist framework (bottle or flask) and adding an option to the MkDocs CLI (serve command) in order to be able to serve only one page. In my first draft, I also worked on integrating markdownlint with the rule configuration (https://github.com/igorshubovych/markdownlint-cli). The idea was to guide the user in the best way possible when writing content.

In my design, I thought that the editor should rather focus on mkdocs taking into account the configuration file. But if it's done with the Material theme, it will be great!

[matchavez]

Not to duplicate, etc., but do we know about https://github.com/qjebbs/vscode-markdown-extended

[squidfunk]

@matchavez thanks for posting! I haven't checked this extension yet, but I'd be curious to hear what works great and what doesn't when editing a Material for MkDocs based project.

[Vasperous]

Very interested in this feature as my current documentation is extremely large and takes forever to build and preview. Like many others I use (and love) Sublime Text. If VSCode was the only option for this then I would likely download it for that purpose only. In either case I would actually like the python option better not just for myself but my team as they all use something a little different.

[squidfunk]

@Vasperous thanks for your input. I'm still trying to figure out the best possible way to build an MVP out of this, as there seem to be different needs. For me, a VS Code extension was the most natural way to go, as I'm currently building one for my startup, but as different people stick to different editors, it may not be the first route to take. Given the time that I need to invest in this topic, I'm looking for a minimal solution that provides the core value, i.e. the fast rendering. I'm currently undertaking a major refactoring of the theme's underlying observable architecture, and as soon as that's finished, I'll have more time on my hands to address this topic again.

[jairbubbles]

@squidfunk I'd really love the VS Code extension, couldn't you rely on the community to create plugins for other code editors (like Sublime)?

[ayeks]

Interesting discussion! We use mkdocs-material as internal platform documentation as well. We accumulated over 1500 commits so far. The documentation grew so big that mkdocs takes some minutes to load. This makes working on the docs interactively with mkdocs serve too slow. When I onboard new teams on the documentation I recommend the following workflow:

• 1. view the generated docs which are deployed with GitLab Pages
• 2. hit the edit button on the page you want to modify
• 3. on the page in GitLab, open the GitLab WebIDE to edit
• 4. do your changes and commit them to a new branch (no one is allowed to push to master because that gets really messy with 30+ contributors)
• 5. create a merge request for your branch, open changes in the merge request if you want to add anything
• 6. markdownlint will check the files, and mkdocs will build with strict
• 7. if the tests are passing, someone from the core team will review the change and merge it into master

This way, the colleagues do not have to deal with pip, poetry and messed up python Windows installations. They completely stay in GitLab for the editing process.

If you can manage to create a in-browser, or in editor preview for only the content part of a page - without the need to run a full mkdocs build it would be really awesome. A lot of colleagues end up with pushing multiple merge requests after another to fix minor mkdocs-material related syntax issues, because their markdown preview tool or the GitLab preview failed to interpret the mkdocs-material syntax.

The solution to the problem would be a VSCode Integration / Browser Editor, that interprets your markdown enhanced syntax. Then the colleagues could copy paste their stuff back and forth. Just like they are doing it with PlantUML.

[jairbubbles]

@ayeks Have you tried using environments with GitLab? It would allow you to review the changes on documentation directly form the merge request page. Sadly GitLab pages does not support so you'll need to rely on another hosting...

[jairbubbles]

(More precisely the review apps)

EDIT: In fact you can make them work with Pages by deploying to subdirectories (https://stackoverflow.com/questions/55596789/deploying-gitlab-pages-for-different-branches)

[ayeks]

@jairbubbles Thanks for your response! Publishing via S3 or similar is not an option for us because we depend on the auth of GitLab for our documention.

However that stackoverflow link looks really promising. I will definitely check this out because this would make our workflow so much smoother! Thanks!

[squidfunk]

Thanks to all of you for the continued input. I think a web-based prototype is probably the best way to see if the general idea works and feels right. If it does, wrapping stuff up in editor extensions could be the next step to pursue.

[jairbubbles]

Something like https://stackedit.io?

[squidfunk]

Basically yes, but with Material-for-MkDocs flavored Markdown with support for admonitions, details, content tabs, nested fences, icons, emojis, etc. I would be super happy if somebody knows a solution that supports all (or parts) of this – I don't know of any. I would be very happy to not put the effort into implementing the live preview 😅 , However, from the feedback we got here, I believe it might improve the workflow of some users.

[jairbubbles]

Sorry, I can't really help. StackEdit is opensource, so maybe you can build on top of it?

https://github.com/benweet/stackedit