Preview: Live Edit – Feedback wanted! #2110
Comments
squidfunk
changed the title
|
I think this could be a killer feature for technical writers. |
|
Do you want feedback on the idea (awesome) or someone to test the proof of concept (I’m in)? |
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
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:
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.). |
|
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 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. |
|
Similar to @Stephen-Gates. 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. |
|
Some thoughts on ideal workflow without fully understanding VS Code + plug-in + Github integration possibilities...
I work solo so don't deal with branches, multiple, and potentially clashing, contributions. Assume VS Code + Github integration can help with this. |
|
Thanks for outlining your workflows!
Yes, that can definitely be implemented and makes a lot of sense.
If we render the preview in an
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. |
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. |
Not sure. It could get me to switch from Sublime, but our Java programmers probably won't leave Eclipse for that :) |
|
This would greatly improve our projects documentation workflow. Im personally fine with using these tool as I'm a developer myself but an even faster rendering time would still be amazing! |
|
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. |
|
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.:
It could essentially be a supercharged version of Markdown Preview which is aware of |
|
@squidfunk: My/our workflow where I work:
PS: I don't find any issue with using |
|
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 So what we currently do is using 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 |
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 |
|
Hi there! This seems to be a killer feature! Especially the in-browser option 😍. To explain why: we use it for a collaborative website (blog and collegial content). Here is our actual workflow:
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 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! |
|
Not to duplicate, etc., but do we know about https://github.com/qjebbs/vscode-markdown-extended |
|
@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. |
|
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. |
|
@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. |
|
@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)? |
|
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
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 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. |
|
Sorry, I can't really help. StackEdit is opensource, so maybe you can build on top of it? |
|
Thank you all again for your great and detailed feedback! I've decided to discontinue the work on this idea, for now. I'm currently not seeing when and how I could find enough time to build an MVP out of this, as there's a lot of hidden complexity that would need to be addressed. Furthermore, this project, as Material for MkDocs itself, would be an endless stream of adding support for more and more features, plugins, and workflows, and I'm afraid I can't maintain two projects of this magnitude. This project alone already keeps me busy most weekends. Maybe sometime in the future, we can revisit this idea, or somebody with enough spare time on their hands pulls it off 😊 |
|
Can you open this up to community development? It seems like there is a lot of interest (myself included) on having a way to preview material for mkdocs. For myself, I'm using Strapi / directus as a CMS for our internal mkdocs sites and I'd love a way to be able to show an accurate preview by having a client-side frame that pulls from a CMS entry. |
|
@Thermal-Shock thanks for suggesting. Unfortunately, I'm currently not considering releasing the source code for several reasons I can't go into detail. I hope for your understanding. |
|
Thanks @squidfunk. I totally understand. I wonder have you considered using PyScript. It also appears to be built upon Pyodide and might make it easier to do a basic preview. |
|
You can certainly preview Markdown content using Pyodide, it is a viable path. I do it here: https://facelessuser.github.io/coloraide/playground/. Just click the notebook icon in the right of the page, edit, and submit. This is of course if you want to only preview content. I haven't specifically looked into PyScript myself. As an example, here's is a page dynamically loaded from a GitHub gist: https://facelessuser.github.io/coloraide/playground/?notebook=https%3A%2F%2Fgist.githubusercontent.com%2Ffacelessuser%2F7c819668b5eb248ecb9ac608d91391cf%2Fraw%2Fplayground.md. This only runs Python Markdown and any plugins loaded. It uses the currently deployed site's CSS, which happens to be Material's. Now, what is tricky is loading all the custom icons that Material provides. That's a lot to load up dynamically into the browser, so that part is not very practical, so we don't have access to those icons. We also aren't running an entire MkDocs server, so we can't get access to any MkDoc plugins either. It just processes content with Python Markdown. Anyways, my point is simply that content previewing is certainly possible for anyone that is motivated, though there may be some limitations. |
|
Thanks for the insight @facelessuser. I see that markdown is only part of the equation. I'm out of my depth here perhaps, but If it was possible to bundle up the mkdocs server rendering into something that could be called by way of PyScript, it feels like that would be very close to having the preview within the browser. But again, I'm sure I'm missing something here and this is not a trivial exercise. I was trying to leverage our existing mkdocs sites but pull all the content from a CMS. I know this is very doable, but an accurate preview with all the theme is where it gets tricky. Worst case, the content authors just have to run a local mkdocs docker instance that detects the need to rebuild and then the Javascript preview is simply an iframe of the result. I think this will work, but means the authors have to have docker for windows etc etc. to see the preview. |
|
Yeah, it seems if you want it completely integrated together, you'd almost have to let MkDocs handle it on the backend and only just send the content from the frontend to the backend. And then you don't even need PyScript. The only way to keep the Markdown rendering integrated with MkDocs is to let MkDocs do the processing of Markdown as it will call Python Markdown in its pipeline. |
|
Any change to having this live edit feature in the near future? This would be amazing to have the tool more wiki-like. Slightly related, is there a way to do incremental build? When does your documentation grow? We are starting to have problems with build time (several minutes to build a small change). |
|
@brunojdo not yet, but it actually might happen at some point. I'll re-evaluate next year 😊
This is a MkDocs question, not Material for MkDocs, that has been asked several times. You can search MkDocs issue tracker for some discussion around the topic, and see how people work around it. It's not simple though. |
|
Great to hear that. Thanks @squidfunk |
This would be great. Major problem I see for adoption among my colleagues is the "difficulty" to document and see changes. They like the whole package but refuse to use it becuase they do not trust the result. In any case, in 2 days the new year starts. If you look for motivation and challenges, this is a nice big one. Thanks for your work. Keep so. |
|
I'm also would like to raise this question Currently, for preview I use docker and it's damn slow I believe, that because of that reason, it's hard to start with Mkdocs and that's why people still prefer confluence Dockerfile, composehttps://github.com/karma-git/kb/tree/master/documentation FROM alpine:3.17
RUN apk add --no-cache \
python3=~3.10 \
py3-pip=~22.3 \
&& pip install --no-cache-dir \
mkdocs-material~=8.5 \
mkdocs-awesome-pages-plugin~=2.8 \
mkdocs-mermaid2-plugin~=0.6
# mkdocs-blog-plugin~=0.25 # NOTE: insiders feature
RUN addgroup --gid 10001 app \
&& adduser \
--uid 10001 \
--home /home/app \
--shell /bin/ash \
--ingroup app \
--disabled-password \
app
USER 10001
WORKDIR /home/app
ENTRYPOINT [ "" ]---
version: '3.8'
services:
mkdocs:
container_name: mkdocs
build: ./
command: ["mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"]
ports:
- "8000:8000"
volumes:
- .:/home/app |
|
We've decided that we'll re-evaluate this feature in the near future. We can't promise how it will turn out and when it's going to arrive, as we have so much in the pipeline right now, but making Material for MkDocs easier to work with for non-technical folks, and making it an alternative for Wikis (and Confluence) is something we're actively considering. We'll start evaluation next year. Our current idea is to make knowledge management inside of organization simpler. If you are working in an organization that uses Material for MkDocs for internal knowledge management, we'd love to learn about your use case! Your feedback would be of tremendous help for us, so we can build something that allows you to switch from an entirely proprietary solutions to something that is based on Open Source, giving you full control over your knowledge. |
|
Great news @squidfunk! Did you see https://www.jetbrains.com/writerside/ ? I didn't look into details but I feel like this might be the next step for "doc as code" (the direction, not the product per itself). |
I know it's been a while and I know this will be a huge undertaking, but it gives me hope to read this. Hope that someday there will be a vscode or obsidian.md extension to handle preview of single pages, no matter who makes it. I'm about to deploy a gitlab-pages + mkdocs + mkdocs-material solution to replace a very old brokedown wiki for a team of 30 or so and I'm quite nervous about this one aspect. Our old wiki didn't use standard markdown and didn't offer even 20% of mkdocs-material's features, but it DID have an in-browser WYSIWYG editor. I'm worried about how our team is going to handle the requirement of merging to main & waiting 60s in order to see whether they got their syntax correct. |
|
@facelessuser said:
Maaaaaan Isaac that is amazing. What you've put together is so powerful and complex that I suspect people are just kind of skipping over it because they don't understand. (That's what I did the first time I read this page and went to your site.) I spent a few minutes looking at your code and I have hope that if I can find the time, I'll be able to figure out how to adapt and implement something similar on our docs site. Like (I suspect) most that will visit this thread, I don't even need the fancy interactive code-execution; just being able to render a single (copy-pasted) md page in browser in the context of an existing mkdocs-material site with all the same mkdocs/markdown extensions and css (even if missing emojis) would be game-changing -- it would fill a huge gap for a lot of doc-writing teams. I know that's not why you made what you made for ColorAide's docs, but if you are ever so inclined to write up a tutorial or something to help others implement that, man... that would be awesome. |
|
I'm reopening this issue, as we're likely going to work on this probably later this year. |
|
WYSIWYG for non-engineer contributors (business users, product managers, technical writers, etc) would be awesome to allow them to contribute to the documentation directly in a github pages hosted documentation and commit it to a PR which could be reviewed by both engineering and non-engineering and then merged in accordingly. |
|
@ryran I think I didn't see this post earlier, but yeah, if you have any questions, feel free to open a discussion. It's probably much simpler if all you actually want to do is parse Markdown. I had a requirement to run Python code in code blocks and generate color previews....and you get the idea, but simply handling the Markdown would be much more simple. The "playground" page lets you completely edit all the Markdown. You can also load raw Markdown from a gist if you point it at the raw link. It'll be cool to see what @squidfunk cooks up as well. Some of the things I write for myself are crafted with popsicle sticks and bubble gum, they hold together well enough and work for what I want them to do, but someone far more competent in the web space I'm sure can craft a very nice solution crafted at a general audience. |
squidfunk
added
needs user feedback
|
Hey @squidfunk , If there is any chance that you could consider opening up your backend implementation to third party clients, or at least try to keep third party clients in mind - that would be awesome. Any level above zero would be well appreciated. I know that this is nothing small or simple to ask for, but asking is free... right? 👼 If you are interested in my project, feel free to take a look, its all open source. My initial intention was to create both a web client as well as a native android client, but limited time (and skill) meant that only the backend and android client is in a usable state right now. Considering there might be an official web solution in the future, that might not be a bad thing though 😄 . Its only a pet project of mine that I work on in my (very limited) free time, so don't expect anything magical from it. Thx for reading, keep up the awesome work! ❤️ |
I haven't really started working on this besides the prototype I showed, which allows to translate Markdown to HTML in-browser, i.e., is a live side-by-side preview, nothing more. I will share progress here, once we start working on it By the way, I have seen that you're working on MkDocsEditor and yet have to check it out |
I use the Markdown preview in VSCode and it works in most cases, but not in all, since it is not Python Markdown and doesn't have its extensions. Namely, in one project, we work with code block snippets and it would tremendously help to verify:
Auto-completing file paths would be nice too, but I suppose, that would be a whole different story. |
and others
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
pipordocker, 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?
The text was updated successfully, but these errors were encountered: