search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
19.34k stars 3.41k forks source link

Preview: Live Edit ā€“ Feedback wanted! #2110

Open squidfunk opened 3 years ago

squidfunk commented 3 years ago

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:

screenshot-localhost-8080-1607899586028

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 commented 3 years ago

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

Stephen-Gates commented 3 years ago

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

squidfunk commented 3 years ago

@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:

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 commented 3 years ago

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.

martinbira commented 3 years ago

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 commented 3 years ago

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.

squidfunk commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

squidfunk commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

@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 commented 3 years ago

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:

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 commented 3 years ago

@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 commented 3 years ago

(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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

Something like https://stackedit.io?

squidfunk commented 3 years ago

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 commented 3 years ago

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

https://github.com/benweet/stackedit

squidfunk commented 3 years ago

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 šŸ˜Š

Thermal-Shock commented 1 year ago

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.

squidfunk commented 1 year ago

@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.

Thermal-Shock commented 1 year ago

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.

facelessuser commented 1 year ago

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.

Thermal-Shock commented 1 year ago

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.

facelessuser commented 1 year ago

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.

brunojdo commented 1 year ago

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).

squidfunk commented 1 year ago

@brunojdo not yet, but it actually might happen at some point. I'll re-evaluate next year šŸ˜Š

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).

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.

brunojdo commented 1 year ago

Great to hear that. Thanks @squidfunk

jromal commented 1 year ago

@brunojdo not yet, but it actually might happen at some point. I'll re-evaluate next year šŸ˜Š

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.

karma-git commented 1 year ago

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, compose https://github.com/karma-git/kb/tree/master/documentation ```Dockerfile 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 [ "" ] ``` ```yaml --- 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 ```
squidfunk commented 8 months ago

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.

You can schedule a Calendly call with me.

jairbubbles commented 8 months ago

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).

ryran commented 4 months ago

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.

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.

ryran commented 4 months ago

@facelessuser said:

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.

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.

squidfunk commented 4 months ago

I'm reopening this issue, as we're likely going to work on this probably later this year.

charlie430 commented 4 months ago

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.

facelessuser commented 4 months ago

@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.

markusressel commented 4 months ago

Hey @squidfunk , I am really looking forward to what you might be able to achieve. I have tried to build my own, dedicated version of this for many years now. To achieve this I had to implement my own, dedicated backend to modify the files within the MkDocs project.

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? :angel:

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 :smile: . 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. https://github.com/MkDocsEditor

Thx for reading, keep up the awesome work! :heart: