feat(gnoweb): readme markdown viewer for p/ & r/ #4101

alexiscolin · 2025-04-10T04:42:41Z

⚠️ WIP — Fixes: #4070

This PR implements a new feature to display README.md files in a formatted way for both pures (p/) and realms (r/) in gno.land. This would apply in Directory template and in Source template.

Changes

Added a new RenderMd method to HTMLWebClient that:
- Takes a path and filename as input
- Reads the markdown file using SourceFile
- Parses and renders the markdown content using the existing ParseMarkdown function
- Generates a table of contents for the markdown content (WIP)
- Returns the rendered content and metadata
Modified the GetDirectoryView handler to:
- Check for the presence of README.md in the directory
- If found, render it using the new RenderMd method
- Display the rendered README content at the top of the directory listing
- Move README.md to the first position in the file list
Reuse code to create a new generateTOC helper method to HTMLWebClient that:
- Takes a parsed markdown document and its content
- Generates a table of contents with configurable depth (2-6 levels - reuse RealmView settings)
In Source template, a markdown file is automatically rendered with Goldmark in HTML:
- Automatically detect and render markdown files (.md) in preview mode
- Add a toggle button to switch between markdown preview and code view
- Support the plain WebQuery to force code view for markdown files

Benefits

Improves documentation visibility by automatically displaying README.md files
Maintains consistent markdown rendering across the platform
Avoid using the render function for md only content that could live in a simple md file
Provides navigation through table of contents for long README files
Integrates seamlessly with existing directory views

Technical Details

Uses the existing Goldmark markdown parser
Maintains the same styling and formatting as realm content
Preserves the ability to view raw source files

This feature enhances the user experience by making documentation more accessible and readable directly in the web interface.

TODO

Display md as html in source (add a switch button code <-> html)
Remove readme sorting (will be implemented)
Style and design
Tests

In Directory template

In Source template

Gno2D2 · 2025-04-10T04:43:50Z

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):

IGNORE the bot requirements for this PR (force green CI check)

✅ Automated Checks (for Contributors):

🟢 Maintainers must be able to edit this pull request (more info)
🟢 Changes related to gnoweb must be reviewed by its codeowners
🟢 Pending initial approval by a review team member, or review from tech-staff

☑️ Contributor Actions:

Fix any issues flagged by automated checks.
Follow the Contributor Checklist to ensure your PR is ready for review.
- Add new tests, or document why they are unnecessary.
- Provide clear examples/screenshots, if necessary.
- Update documentation, if required.
- Ensure no breaking changes, or include BREAKING CHANGE notes.
- Link related issues/PRs, where applicable.

☑️ Reviewer Actions:

Complete manual checks for the PR, including the guidelines and additional checks if applicable.

📚 Resources:

Debug

Automated Checks

Maintainers must be able to edit this pull request (more info)

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 The pull request was created from a fork (head branch repo: alexiscolin/gno)

Then

🟢 Requirement satisfied
└── 🟢 Maintainer can modify this pull request

Changes related to gnoweb must be reviewed by its codeowners

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 A changed file matches this pattern: ^gno.land/pkg/gnoweb/ (filename: gno.land/pkg/gnoweb/app_test.go)

Then

🟢 Requirement satisfied
└── 🟢 Or
    ├── 🔴 This user reviewed pull request: alexiscolin
    └── 🟢 This user reviewed pull request: gfanton

Pending initial approval by a review team member, or review from tech-staff

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 Not (🔴 Pull request author is a member of the team: tech-staff)

Then

🟢 Requirement satisfied
└── 🟢 If
    ├── 🟢 Condition
    │   └── 🟢 Or
    │       ├── 🔴 At least 1 user(s) of the organization reviewed the pull request (with state "APPROVED")
    │       ├── 🟢 At least 1 user(s) of the team tech-staff reviewed pull request
    │       └── 🟢 This pull request is a draft
    └── 🟢 Then
        └── 🟢 Not (🔴 This label is applied to pull request: review/triage-pending)

Manual Checks

**IGNORE** the bot requirements for this PR (force green CI check)
If
🟢 Condition met
└── 🟢 On every pull request
Can be checked by

Any user with comment edit permission

codecov · 2025-04-10T13:03:28Z

Codecov Report

Attention: Patch coverage is 68.66667% with 47 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
gno.land/pkg/gnoweb/webclient_html.go	29.26%	25 Missing and 4 partials ⚠️
gno.land/pkg/gnoweb/handler.go	75.51%	9 Missing and 3 partials ⚠️
gno.land/pkg/gnoweb/webclient_mock.go	85.00%	4 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

gfanton

First comment pass; I need to delve deeper for a full review, but I will wait for you to resolve the preliminary comments.

gfanton · 2025-04-11T09:57:13Z

gno.land/pkg/gnoweb/webclient_mock.go

+		markdown: goldmark.New(
+			goldmark.WithExtensions(
+				markdown.GnoExtension,
+			),
+		),


the mock cannot depend on goldmark

gfanton · 2025-04-11T09:58:36Z

gno.land/pkg/gnoweb/webclient_html_test.go

This test file doesn't make sense, you are not testing html client but the mock itself.
If no tests were existing before, it is because we need to have a mock for the RPC client itself to be able to test the HTML client.

gfanton · 2025-04-11T10:01:04Z

gno.land/pkg/gnoweb/webclient_html.go

+	// If writer is nil, just return metadata
+	if w == nil {
+		return &fileMeta, nil
+	}
+


writer cannot and should not be nil; remove this. it will complexity the caller logic

gfanton · 2025-04-11T10:05:18Z

gno.land/pkg/gnoweb/webclient_html.go

+}
+
+// RenderMd renders a markdown file and returns the rendered content
+func (s *HTMLWebClient) RenderMd(w io.Writer, u *weburl.GnoURL, fileName string) (*RealmMeta, error) {


Suggested change

func (s *HTMLWebClient) RenderMd(w io.Writer, u *weburl.GnoURL, fileName string) (*RealmMeta, error) {

func (s *HTMLWebClient) RenderMarkdownFile(w io.Writer, u *weburl.GnoURL, fileName string) (*RealmMeta, error) {

gfanton · 2025-04-11T10:09:43Z

gno.land/pkg/gnoweb/components/view_source.go

+type DisplayMode int
+
+const (
+	ModeCode DisplayMode = iota
+	ModeMarkdown
+)


No, if you are using this within the template, it makes no sense to use int here. Just change this to string, or find a way to expose this as const within the template. But if it's not something simple, simply use string.

Suggested change

type DisplayMode int

const (

ModeCode DisplayMode = iota

ModeMarkdown

)

type DisplayMode string

const (

ModeCode DisplayMode = "code"

ModeMarkdown = "markdown"

)

thehowl · 2025-07-02T11:57:04Z

closing in favour of #4401

This PR implements `README.md` file support for both `pures` (p/) and `realms` (r/) in gno.land, addressing the requirements outlined in #4070. ## Features ### For p/ packages: - If a `README.md` exists, it is rendered at the top of the directory listing (in the `content` temaplte) - `README.md` is moved to the first position in the file list - The rendered content uses the existing Goldmark infrastructure with Gno extensions ### For r/ realms: - No Render() & no README.md: Display error page - Render() & no README.md: Works as before (existing behavior) - No Render() & README.md: Fallback to README.md rendering - Both present: Call `Render()` as primary, with `README.md` available in source view ## Next iteration This PR adds the first step to build the pkg.go template in gnoweb instead of the directory template and restructure the source template to be linked to it. This will improve and simplify the UX while giving more features/info to the users. **_Note**: This PR replaces the previous PR #4101 with a much cleaner and more maintainable implementation. The current code reuses existing infrastructure and avoids code duplication, while providing a consistent user experience for displaying `README.md` files._ <img width="1384" alt="Capture d’écran 2025-06-22 à 13 18 45" src="https://github.com/user-attachments/assets/61248889-11a5-48b5-b0c0-2bb4a6f56200" /> <img width="1380" alt="Capture d’écran 2025-06-22 à 13 55 48" src="https://github.com/user-attachments/assets/b976b373-c2ce-4f7b-bafe-3ec6c32abd5e" /> --------- Co-authored-by: Morgan Bazalgette <morgan@morganbaz.com>

This PR implements `README.md` file support for both `pures` (p/) and `realms` (r/) in gno.land, addressing the requirements outlined in gnolang#4070. ## Features ### For p/ packages: - If a `README.md` exists, it is rendered at the top of the directory listing (in the `content` temaplte) - `README.md` is moved to the first position in the file list - The rendered content uses the existing Goldmark infrastructure with Gno extensions ### For r/ realms: - No Render() & no README.md: Display error page - Render() & no README.md: Works as before (existing behavior) - No Render() & README.md: Fallback to README.md rendering - Both present: Call `Render()` as primary, with `README.md` available in source view ## Next iteration This PR adds the first step to build the pkg.go template in gnoweb instead of the directory template and restructure the source template to be linked to it. This will improve and simplify the UX while giving more features/info to the users. **_Note**: This PR replaces the previous PR gnolang#4101 with a much cleaner and more maintainable implementation. The current code reuses existing infrastructure and avoids code duplication, while providing a consistent user experience for displaying `README.md` files._ <img width="1384" alt="Capture d’écran 2025-06-22 à 13 18 45" src="https://github.com/user-attachments/assets/61248889-11a5-48b5-b0c0-2bb4a6f56200" /> <img width="1380" alt="Capture d’écran 2025-06-22 à 13 55 48" src="https://github.com/user-attachments/assets/b976b373-c2ce-4f7b-bafe-3ec6c32abd5e" /> --------- Co-authored-by: Morgan Bazalgette <morgan@morganbaz.com>

alexiscolin added 2 commits April 9, 2025 15:08

feat: readme viewer

b696faa

feat: read markdown from directory

80117b0

github-project-automation bot added this to 💪 Bounties & Worx and 🧙‍♂️gno.land core team Apr 10, 2025

github-project-automation bot moved this to Triage in 🧙‍♂️gno.land core team Apr 10, 2025

alexiscolin marked this pull request as draft April 10, 2025 04:42

github-actions bot added the 📦 ⛰️ gno.land Issues or PRs gno.land package related label Apr 10, 2025

github-actions bot assigned alexiscolin Apr 10, 2025

Gno2D2 requested a review from gfanton April 10, 2025 04:43

alexiscolin added the 🌍 gnoweb Issues & PRs related to gnoweb and render label Apr 10, 2025

alexiscolin added 8 commits April 10, 2025 14:05

refactor: remove readme sorting

367e703

Merge branch 'master' into feat/gnoweb-source-readme-viewer

0ff7d79

fix: comments

2394941

feat: add md style and fix ext_links

a4e4d05

fix: add renderMd in mock

8fc2ffe

feat: render markdown in source page

e27525b

fix: tests

2e068b1

Merge branch 'master' into feat/gnoweb-source-readme-viewer

771a9d3

alexiscolin and others added 10 commits April 11, 2025 00:25

feat: webclient_html tests

908b077

fix: lint

63ab36f

fix: tests

73caa21

Merge branch 'master' into feat/gnoweb-source-readme-viewer

3e5d976

fix: tests

05a698c

chore: lint

6e860be

chore: add tests

53ea20f

Merge branch 'gnolang:master' into feat/gnoweb-source-readme-viewer

347a21a

fix: tests

fc637bf

fix: linter

14b7930

gfanton reviewed Apr 11, 2025

View reviewed changes

jaekwon force-pushed the master branch from d3e0886 to 705e0df Compare May 3, 2025 20:18

alexiscolin mentioned this pull request Jun 22, 2025

feat(gnoweb): README.md support for p/ & r/ packages #4401

Merged

thehowl closed this Jul 2, 2025

github-project-automation bot moved this from Triage to Done in 🧙‍♂️gno.land core team Jul 2, 2025

github-project-automation bot moved this to Done in 💪 Bounties & Worx Jul 2, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(gnoweb): readme markdown viewer for p/ & r/ #4101

feat(gnoweb): readme markdown viewer for p/ & r/ #4101

Uh oh!

alexiscolin commented Apr 10, 2025 •

edited

Loading

Uh oh!

Gno2D2 commented Apr 10, 2025 •

edited

Loading

✅ Automated Checks (for Contributors):

☑️ Contributor Actions:

☑️ Reviewer Actions:

📚 Resources:

If

Then

If

Then

If

Then

If

Can be checked by

Uh oh!

codecov bot commented Apr 10, 2025 •

edited

Loading

Uh oh!

gfanton left a comment •

edited

Loading

Uh oh!

gfanton Apr 11, 2025

Uh oh!

gfanton Apr 11, 2025

Uh oh!

gfanton Apr 11, 2025

Uh oh!

gfanton Apr 11, 2025

Uh oh!

gfanton Apr 11, 2025

Uh oh!

thehowl commented Jul 2, 2025

Uh oh!

Uh oh!

	func (s HTMLWebClient) RenderMd(w io.Writer, u weburl.GnoURL, fileName string) (*RealmMeta, error) {
	func (s HTMLWebClient) RenderMarkdownFile(w io.Writer, u weburl.GnoURL, fileName string) (*RealmMeta, error) {

feat(gnoweb): readme markdown viewer for p/ & r/ #4101

feat(gnoweb): readme markdown viewer for p/ & r/ #4101

Uh oh!

Conversation

alexiscolin commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Benefits

Technical Details

TODO

In Directory template

In Source template

Uh oh!

Gno2D2 commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛠 PR Checks Summary

Manual Checks (for Reviewers):

✅ Automated Checks (for Contributors):

☑️ Contributor Actions:

☑️ Reviewer Actions:

📚 Resources:

If

Then

If

Then

If

Then

If

Can be checked by

Uh oh!

codecov bot commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gfanton left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gfanton Apr 11, 2025

Choose a reason for hiding this comment

Uh oh!

gfanton Apr 11, 2025

Choose a reason for hiding this comment

Uh oh!

gfanton Apr 11, 2025

Choose a reason for hiding this comment

Uh oh!

gfanton Apr 11, 2025

Choose a reason for hiding this comment

Uh oh!

gfanton Apr 11, 2025

Choose a reason for hiding this comment

Uh oh!

thehowl commented Jul 2, 2025

Uh oh!

Uh oh!

alexiscolin commented Apr 10, 2025 •

edited

Loading

Gno2D2 commented Apr 10, 2025 •

edited

Loading

codecov bot commented Apr 10, 2025 •

edited

Loading

gfanton left a comment •

edited

Loading