[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

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

[yhatt]

The Marp team's entrance repository has disabled GitHub Issues to centralize the forum about the overall Marp ecosystem within GitHub Discussions.

This inability to use Issues for building and developing the documentation site can pose challenges for contributors to the open-source project. It becomes difficult to track the remaining tasks, their progress, and the context for each task.

Using Issues also offers several advantages that enhance development efficiency, such as automatic closing of issues through pull requests and automation features linked to Projects Kanban boards. These features streamline collaboration and task management.

It might seem like simply enabling Issues would be a straightforward solution, but there are reasons why we have not done so. In short, we needed to avoid scope creep.

In Classic Marp (yhatt/marp), a wide variety of requests and opinions beyond the repository’s intended scope were concentrated in Issues. This not only blurred the project’s scope and confused contributors but also made management increasingly difficult. As a result, we had experienced project burnout once. 🔥

Learning from that experience, we now operate using a multi-repository approach, with clearly defined scopes and reporting lines for each tool.

If Issues were enabled in the entrance repository, there is a risk that bug reports and feature requests would once again converge in a single place, potentially leading to a repeat of past mistakes. For this reason, we prefer to avoid enabling Issues.

GitHub Projects allows Issues to be tracked across repositories, so having the project housed in the marp-team/marp repository might not pose a significant problem. However, considering ease of contribution for documentation contributors, it would be better to manage the content of the site in a new repository where issues are enabled.

[callandret]

@yhatt, I've been thinking about the consideration of moving the website to its own repo, and for the time being, I think it makes sense to keep the website/docs in the entrance repo. The rest of the Marp repos are organized functionally, and it seems logical to me for the entrance repo to contain the website and docs.

Also, since there has already been lots of discussion about updating the docs within this repo, it would make it easier to reference those by keeping them in the same place.

I still think it would be helpful to track work on the documentation updates with a Gihub Project. Creating a project would allow me to list out the tasks that I'll be working on related to the docs so you can see what I'm working on, what I'm planning to do, and the status of each deliverable.

It looks like you can provide access to a project without providing access to the whole repo, so I'd be able to edit/manage the project without touching/affecting anything in the repo: https://docs.github.com/en/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects

I'm envisioning a project called "Marp Documentation Upgrade 2025" and within the project, I'd list the key tasks and subtasks related to this initiative. Again, keeping the project within the same repo as the website and discussion forum would make it easy to reference prior conversations related to this initiative.

I am a project manager in my day-to-day work, and I find it extremely helpful and valuable to have a place to document and track work. When it's a collaboration, it's helpful to make that work visible to others.

Let me know what you think about this approach. I'd like to take the latter part of 2024 to plan out this work more fully so I can move into editing/writing mode in early 2025 after you update the site.

[yhatt]

My opinion about the repository migration remains unchanged as detailed in the previous thread.

Regarding GitHub Projects, I have created an empty project #3. Feel free to edit the project as needed.

Outside collaborators are required to apply non-controllable permission to 1+ repositories, which is too broad in scope. Instead, I have prepared the @marp-team/documentation-team, which has granular permissions, and I'm inviting.

[callandret]

@yhatt Thank you for creating the project and adding me to it! I've started adding some key tasks for planning the path forward. You can check those out in the project: https://github.com/orgs/marp-team/projects/3

A few things to note:

• The timeframes for tasks are arbitrary at this point. I added start/end dates for the tasks as a starting point for discussion. I am unsure of your bandwidth and the time required to migrate the docs to a new repo.
• Per your comment above, you recommended waiting to fork the repo until after the migration, and I agree with that guidance. In the meantime, I can start assessing the state of the current docs, but I'll hold off on doing any technical writing until the migration is complete.
• All of the tasks are in draft form because Issues are disabled in the Marp repo.

My requests:

• Please let me know a reasonable target date for completing the migration to the new repository. That will enable me to plan my content audit and subsequent drafting of new docs more effectively.
• If it seems appropriate to you, please enable issues for the new repository, so I can link project task to issues in that repo for more effective tracking.

This is its own initiative/project, but it may be helpful to discuss guidelines for contributions in the future to help direct people to have effective discussions/issue creation. Perhaps working on the updated docs can be an opportunity to work out what those contribution guidelines can look like.

Thanks again for opening up a path to let me contribute to this project.