[In progress] The unified documentation for Marp

[yhatt]

As mentioned at https://marp.app/blog/re-creation-of-marp-website, our documentations are scattered to many repos and making confusion when learning overall of Marp.

We're working for the unified documentation hosted in marp.app. Many pages are a stub and not yet ready for public but you can peek docs working in progress at https://marp.app/docs/.

[pierre-haessig]

This looks great! Indeed, as a occasional but regularly returning user of Marp, it's sometimes difficult to dig into advanced topics like theme customization or custom themes. The new docs are promising.

Now, I've just discovered the pretty useful color customization of Gaia and Uncover themes from PR #221 and I wonder what is the best place to put the documentation fragment that you put in the PR:

• in the existing doc about Marpit directives, themes section https://marpit.marp.app/directives?id=theme?
• or in the new theme guide https://marp.app/docs/guide/theme ?
• somewhere else?

[yhatt]

I hope to put it in the new theme guide. I want to contain an extensive guide in the new one.
https://github.com/marp-team/marp/blob/main/website/docs/guide/theme.md

NOTE: In the near future, the guide would update by the change of marp-team/marp-core#244. (!important will be no longer required)

An important thing for thinking about this is that we are essentially thinking about Marpit and Marp separately. Marpit's documentation is targeted at "developers using the framework", and we have not assumed reading by Marp consumers, On the other hand, the new guide is targeted to consumers.

[pierre-haessig]

I've been experimenting on drawing a global map of the Marp ecosystem to guide newcomers. This is in the same spirit of the https://marp.app/ homepage, but with explicit links.

This is the link to the source for Diagrams.net: https://gist.github.com/pierre-haessig/e936294d2bb70514376ed952df2d4a44

This is a first draft. Let me know what you think (that is: is it worth polishing?).

PNG export (for some reason, the Marp logo on top is not exported)

[yhatt]

Looks awesome! This diagram would help project contributors to know the architecture. 😄
We already have a simple diagram for that in the contributing guideline of marp-team projects, but this diagram is showing the current architecture clearer.

Of course, we accept the pull request to update "Architecture" section: https://github.com/marp-team/.github. FYI making separate ARCHITECTURE.md is also good option.
https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html

On the other hand, it would be not good design if recognizing this architecture was required to all of Marp users. If the new guide has mentioned to this diagram, it would have to be for advanced and developers. (At the same time, all of features in the ecosystem should be covered in the new docs)

[chenxizhang]

very nice

[spkane]

@yhatt I am just wondering if there has been any progress on providing documentation for custom theme generation that is more user/consumer orientated than the current documentation? Maybe a blog post or the like that covers this.

I am interested in creating a new theme for Marp for my work, but CSS is not my strong point. Although I have been able to tweak one of the themes for my needs, I'd like to have someone create a new theme for my use case and some good documentation would be very useful (at least for the things that are more unique to Marpkit).

[yhatt]

In Marpit, styling the slide with CSS has no unique/specific features than CSS for the web. So we believe that existing materials for learning CSS in the world are still useful. Even if we had written an article, I do not think there would be anything new about CSS styling.

Marp's theming system (extended Marpit, and provided by Marp Core) may have value for writing an article, but it is too advanced part and most consumers should not need to care about it.

And I'm not a native English speaker, so writing natural articles and docs for non-developers is more painful than you might think. I always bet on the spirit of open source: writing documentation and articles is also a way to contribute to us.
https://opensource.guide/how-to-contribute/#what-it-means-to-contribute

[spkane]

Thank you for the reply. That makes sense. I'll likely fork one of the existing themes, maybe Gaia, and try to create some new CSS from there.

[callandret]

Hello! I added this comment to an answered question in (#503), and then realized this is probably the better place to put it. Apologies for the duplicate.

I've been using Marp to create lightweight slides for producing instructional training videos at work, and I love how easy it makes things.

I was just thinking this past week that the docs should be updated to support quick answers to common questions while showcasing the versatility and extensibility of Marp.

I've cloned the repo, and I started reorganizing the pages for the in-progress site into an updated structure. I'm not sure if this is the best place to put this, but I wanted to tag on to this existing discussion to say I'm interested in improving the Marp docs.

Below is the output of the draft page structure:

➜  docs git:(docs_update) ✗ tree

├── appearance
│   ├── editing-theme-settings.md
│   ├── fonts.md
│   └── theme.md
├── exporting
├── getting started
│   ├── how-to-write-slides.md
│   ├── installation.md
│   └── whats-marp.md
├── images
│   └── image-syntax.md
├── layout
│   ├── fitting-header.md
│   ├── formatting-slides-with-directives.md
│   ├── heading-divider.md
│   └── page-numbers.md
├── manifest.yaml
├── text-formatting
│   ├── code.md
│   ├── fragmented-list.md
│   └── math-typesetting.md
└── tools
    ├── marp-cli.md
    └── marp-for-vs-code.md

In short, I think all docs should be categorized under logical headings based on questions that people ask, such as "How do I format slides?" and "How do I use images?"

The top-level categories can remain relatively consistent even as Marp evolves.

Structure Overview

• Quick Start gives people the basics they need to get going quickly
• Appearance covers general formatting topics
• Images covers everything related to images
• Text Formatting get into specifics about styling specific types of text
• Layout covers slide layout
• Exporting provides instructions on exporting and displaying Marp prezos in various formats.

I'm 100% open to suggestions, revisions, and corrections. I'm simply trying to address all of the main questions that I've encountered while using Marp, and I think this type of content structure will help more people get up and running with this amazing tool.

Questions

• Does this draft structure make sense?
• Are there topics that are missing?

I'd like to do some more reorganization of the pages and the existing documentation so we can maybe push an initial version of the updated site to get feedback. Thoughts?

Thanks for reading!

—J

[callandret]

@yhatt Thank you! I'm glad you feel the principles and architecture are thoroughly considered—I want to make things easy for newcomers and experienced users alike.

Nextra looks pretty cool—I have not used it before, but as long as I know where to add Markdown files, I can work with that. I also have some experience with CSS from working on WordPress sites, so I can help with that if that need arises.

Proposed Project Phases

It sounds like there are at least two phases to this initiative:

• Phase 1: Build Out Updated Help Docs: This phase can commence as soon as there is approval on the organization of topics that I've outlined above. The writing, organization, and editing of help docs is platform-agnostic, and needs to be done regardless of what SSG Marp uses for documentation.
• Phase 2: Platform Migration to Nextra: Once the docs are in a good spot, the new site can be designed and built, and then the domain marp.app pointed to it.

Since you already have a working documentation site, I recommend focusing on completing Phase 1 before moving to a different platform. It seems to me like having easy-to-navigate documentation is a high-value feature for users, and it would benefit the project to get that out as quickly as possible. Doing so seems pretty straightforward, especially since you have a draft set up from 2021 (that's the place where I've been working in my forked repo). We simply need to get the docs to a place where we feel comfortable launching and then add a top level link called "Guides" or "Manual" to the navbar.

This is perhaps a different discussion, but also think it makes sense from an release/announcement standpoint to do the following:

• Q1 (as close to January 1 as possible)—publish a blog post announcing the new and improved help docs.
• Q2 (between April and May)—announce new Nextra platform with improved TOC navigation and search capabilities.

In between those major releases, we could start publishing changelog announcements through the blog.

Overall, I think that improved documentation has the potential to get more people using Marp and contributing back to the ecosystem, and so I'm thinking about how we can release updated docs quickly so we can iterate.

Discussion Points

• What do you think of the proposed phases?
• Re: terminology, I feel like "Guides" suggests a step-by-step walkthrough of how to do something, whereas the base documentation we need to create is more reference material. I think a Guide would be something like, "How to create your own theme in Markdown" With this in mind, I recommend using the term "Manual," "Docs," or "Help Docs" as the top-level descriptor for documentation. What are your thoughts?
• I am ready to begin auditing the existing docs to see what we have, what's missing, and what can wait to be created. Is there anything you need from me before starting this process?
• I don't think our goal should be comprehensive documentation at this point. I think we're looking for a great first iteration that will be a major refresh for the structure and navigability of the docs. With that said, what are your thoughts about setting up a Project to track and prioritize the docs that need to be created? I can help set this up if desired.

Thank you so much for the quick feedback! I'm very excited to be having this discussion.

[yhatt]

There is still a blocker (Phase 0) that need to be resolved to achieve the proposed phases. Note that following explanation is also including upcoming around tasks of the Marp team.

We plan to publish a blog post within 2024 following the previous article format, covering the latest ecosystem update Marp Core v4, Marp CLI v4, and the upcoming Marp for VS Code v2. Since these updates involve breaking changes that may affect existing slides, it is important to notify users widely and rapidly on not only this forum but also the web site.

Considering this, the tasks we should prioritize by the end of the year are as follows (It's likely that I can only address these tasks during the holiday week in last of the year because of my other projects):

1. Update the VS Code extension to v2: That is including to update the integrated Marp Core and Marp CLI to v4. See also Bump @marp-team/marp-core from 3.9.0 to 4.0.0 marp-vscode#462.
2. Restore the current marp.app to a maintainable state [BLOCKER]: The current state of marp.app is outdated in terms of its codebase, fails to pass audit reports for vulnerability, and will mark every pull requests as fail. Unless this is resolved, it may not be possible to update either the current documentation or blog posts.
3. Publish a blog post highlighting the latest updates in Marp ecosystem: To provide a more comprehensive explanation of the important updates as soon.

The update of Next.js is included in task 2. After than, marp.app will become to allow pull requests for updating docs, and ready for integrating Nextra to existing Next.js.

Having said that, there is no need to wait for that phase with to renew the documentation, so I think there is no issue with working on progress to update docs on the forked repository.

[callandret]

@yhatt Thanks for the additional details. Just to make sure I'm understanding correctly: marp.app needs to move from Jekyll to Next.js so pull requests can actually pass. Correct?

Based on your previous comment, I will start restructuring and organizing docs on my local fork of the Marp project. Since I haven't done any content writing yet, does it make more sense for me to wait until you've migrated to Next.js and fork that? I'm trying to reduce duplicate work/having to migrate Markdown files from one place to another if possible.

If it's OK to continue working in the forked repo as-is, I can submit pull requests so you can see my progress, but I won't expect for pull requests to be merged until the migration to Next.js. I just want to have a place to discuss/review progress.

In addition, my timeframe is similar to yours—I will have time to make some forward progress during the very last week of the year and the beginning of Q1.

Also, can we update the Marp Roadmap and move the Unified documentations on Marp.app task to In Progress? Feel free to list me as an assignee.

Thank you!

[yhatt]

marp.app needs to move from Jekyll to Next.js so pull requests can actually pass. Correct?

The goal for pull requests is correct. However, marp.app is already built with Next.js, and Jekyll is not used. Therefore, the changes will mainly involve upgrading dependencies, and we are not planning significant changes to the structure of the documentation files. Having said that, if you want to avoid duplicate work, it would be better to wait until the updates are complete before forking.

BTW the current marp.app is on the marp-team/marp repository. However, this repository serves as an entrance repository intended for hosting this discussion forum, which makes it difficult to manage progress of working using issues or projects. Would it be more efficient to migrate the website to a new repository such as marp-team/website for better management?

[callandret]

@yhatt What would be the pros and cons of moving the website to it's own repo?

I'm open either way—I think our goal should be to make things cohesive and accessible from a contribution and project management point of view. If a separate repo helps that goal, I agree with that approach.

At the same time, I wonder if it would be helpful to keep things in the same repo and use tags to categorize issues.

Also, to decrease double work, I'll wait to fork the repo once you've done the required upgrades to the site. I did very minimal work to rebuild the file structure, and my work is documented here, so it will be easy to recreate when the time comes.

In the meantime, I can begin audit the existing documentation to identify gaps and opportunities. I'd like to record that process within a Project. Can I be given access to create a standalone project in the repo? I'm not sure how that works, but I'd like my process to be open and transparent for discussion.