Mkdocs-material: 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!