Marp docs should be more accessible/easier to read

[nopeless]

Marp docs feel scattered and are hard to read/find what I want

An example doc format would look like this

Marp YAML

marp
paginate
backgroundImage
style

---

<!-- _class: my-class -->

![bg right]()

something more tangible and clickable like this would make more sense

[yhatt]

Currently you can peek the unified docs at https://marp.app/docs. (#126)

The ecosystem Marp itself and surrounding are constantly changing, and there is a plan to rebuild the website that is a bit gathering dust. So currently the unified docs is not yet preparing. We continue to welcome open feedback on the documentation.

[nopeless]

will there ever be a search function? additionally, there should be a single marp file with all the configuration and links provided next to them. like https://www.nginx.com/resources/wiki/start/topics/examples/full/

[callandret]

Hello! 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 covers exporting Marp decks in a variety of 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.

Thanks for reading!

—J

[yhatt]

@nopeless Uh yes. Explaining Markdown/CommonMark syntax that isn't specific to Marp might end up being redundant since it just would repeat the guide already available on other sites.

What I would really enjoy is a big marp file with all features and commented as sort of a "cheat sheet"

Perhaps this Marp slide might resemble what you're aiming for. It’s a document-cum-slide that was created 5 years ago, but there haven’t been any significant changes to its content up to now.

https://gist.github.com/yhatt/a7d33a306a87ff634df7bb96aab058b5
https://speakerdeck.com/yhatt/marp-basic-example

In my opinion, creating a unified Marp Markdown that combines slides and helps for all features as a single Markdown file might lead to Markdown becoming bloated, because the current Marp is having much features. Even if searchability were improved, it might still be less approachable for general users compared to the clear subject classifications mentioned by @callandret.

That said, as mentioned by #545, twe also should consider about the value of having concrete Marp Markdown document(s) as a sample for Marp. Since this topic has not yet reached a clear conclusion, we continue to welcome open discussions :)

[nopeless]

The single file is for users who are coming back, not users who are learning and I guess putting it at the end of the index would remedy your concern

[callandret]

Hello and thanks for the feedback! I think some guiding principles for documentation might help us reach a decision. I'll outline my recommendations below:

Documentation Principles

• Focus on documenting things specific to Marp. Markdown is already well-documented at many places, and we should assume that users already have a grasp of Markdown. If not, we should point them to other resources like CommonMark.
• Link to high-quality external guides as much as possible. We should assume a basic familiarity with Markdown, HTML, and CSS. We can link to the Mozilla Developer Network, freeCodeCamp, or other resources if people need help with those technologies first.
• Organize topics into logical categories. When I've needed to search for help using Marp in the past, I've found myself scrolling up and down the page and consulting third-party blogs for answers to pretty easy questions such as "How do I invert a theme?" The content structure I'm proposing facilitates the goal of finding answers quickly simply by clicking on topics in the sidebar. If implemented, it will also have the net effect of making it possible to interlink between topics (eliminating redundant documentation).
• Prioritize short doc topics over longer ones. This ties to the previous point. When a single doc covers a broad range of topics, it makes it more difficult to traverse and search through. Short topics will also help make the documentation more scalable as features are added to Marp.

Updated File Structure

Based on the conversation from @yhatt and @nopeless, I updated my draft file structure. I renamed "Getting Started" to "Quick Start" so we can add a Cheat Sheet Syntax Page. I imagine for many users that it would be the most visited page.

 docs git:(docs_update) ✗ tree
.
├── appearance
│   ├── editing-theme-settings.md
│   ├── fonts.md
│   └── theme.md
├── exporting
├── images
│   └── image-syntax.md
├── layout
│   ├── fitting-header.md
│   ├── formatting-slides-with-directives.md
│   ├── heading-divider.md
│   └── page-numbers.md
├── manifest.yaml
├── quick start
│   ├── how-to-write-slides.md
│   ├── installation.md
│   ├── marp-syntax-cheat-sheet.md
│   └── whats-marp.md
├── text-formatting
│   ├── code.md
│   ├── fragmented-list.md
│   └── math-typesetting.md
└── tools
    ├── marp-cli.md
    └── marp-for-vs-code.md

Inspiration Examples

I'm inspired by the following docs:

• Obsidian. I use Obsidian exclusively for notetaking and writing because it supports Markdown formatting. Their documentation structure matches the points I've outlined above, which has made it extremely easy to find help with common questions.
• Markdown Guide. The Cheat Sheet there is great. @nopeless, is this something like what you have in mind?

Based on my experience with the Marp docs and using Marp, I think we should focus on the following tasks:

1. Create a logical content structure to address common user needs when getting started with Marp.
2. Migrate all existing help documentation into that structure, breaking content into unique pages as needed.
3. Adding a header link to the new docs from the site.

Rather than focus on creating extensive documentation about Marp right now, I think we should aim to launch a new version of the docs as quickly as possible. The launch can be followed up by a blog post, social media posts, etc., and we can ask the community to add issues to let us know where we should focus our efforts. That way, we'll get updated docs in front of more people, and we'll get the feedback we need to really build things out.

@yhatt I'm willing to help move things forward with updated documentation following the steps above. I really like this project, and I think updated docs will help it grow.

[nopeless]

@callandret what I had in mind was something like https://learnxinyminutes.com/docs/lua

[yhatt]

@callandret Thanks for your suggestions. The updated principle is well-considered and sounds reasonable. Let us continue to discuss about that at the root discussion thread #126.

@nopeless The provided Lua guide may not be comprehensible, as its clarity can vary depending on individual language familiarity. At least for me, it didn't seem particularly accessible.

For now, rather than taking official primary action as Marp for that, it would be more natural to leave this to the action of the community, because we should prioritize to #126.

In fact, as the position of a member of the Marp community instead of the Marp team, I have already provided the already mentioned resource on Gist.