Markdown/UI templating framework competition

[moul]

We are launching a bounty to find an idiomatic and straightforward Gno API for generating simple markdown, focusing on standard markdown.

While we are considering extending or flavoring markdown in the future (#439), the primary goal of this competition is to identify a library that everyone will prefer over manual string concatenation.

Participants are invited to consider principles similar to GoHugo's use of text/template, the current p/demo/ui (#903), and to analyze other implementations. As in any other language, competition for the best templating system is always intense, and we expect to find a leading framework by adoption. It may also make sense to have a "second most-favorited" or even a third implementation, particularly if the implementations are opinionated and stylistically different.

We expect multiple participants and will share the bounty based on the effort and quality of the submissions. Bounties will be distributed progressively towards the best implementations. This competition will also provide valuable insights for our ongoing work on markdown extensions.

Currently, we suggest that you open your library in p/demo/ui/; we'll eventually reorganize the examples folder later. Additionally, make sure to update at least one or some contracts using your libraries, so we can have usage examples.

Good luck!

---

Edit: We're not looking for a Markdown to HTML library or an HTML framework. We are seeking a Markdown framework that allows us to write idiomatic Gno and generate Markdown.

---

Bounty Size: M; expected maximum reward: $2,000.

Find out more on the bounty program. If you participate with intention of receiving the bounty, you must agree to the Bounty Terms and Conditions.

More bounties | Contributing guidelines

[Nemanya8]

I've been working on a approach that focuses on simplicity. The idea is to bypass the traditional Markdown parsing and directly convert function calls to HTML, minimizing computation and complexity. Below is a demonstration of how this approach works and the output it produces.

Example Render Function

func Render(_ string) string {
	md := mdify.New()

	md.H1("Welcome to Gno Markdown! in h1")
	md.H2("Welcome to Gno Markdown! in h2")
	md.H3("Welcome to Gno Markdown! in h3")
	
	md.P("This is a sample paragraph in markdown.")

	items := []string{"Item 1", "Item 2", "Item 3"}
	md.UL(items)

	orderedItems := []string{"First", "Second", "Third"}
	md.OL(orderedItems)

	md.BR()

	md.Code("go", code)

	result := md.Render()
	return result
}

This implementation is designed to be easy to understand and use. By using this aproach we remove customization and we only focus on basic Markdown functions.

API Implementation Details

type HTML struct {
    content []string
}

func New() *HTML {
    return &HTML{}
}

func (html *HTML) H1(text string) {
	html.content = append(html.content, "<h1>" + text + "</h1>")
}

func (html *HTML) UL(items []string) {
	html.content = append(html.content, "<ul>")
	for _, item := range items {
		html.content = append(html.content, "<li>"+item+"</li>")
	}
	html.content = append(html.content, "</ul>")
}

func (html *HTML) Code(language, code string) {
	if language == "" {
		html.content = append(html.content, "<pre><code>"+code+"</code></pre>")
	} else {
		html.content = append(html.content, "<pre><code class=\"language-"+language+"\">"+code+"</code></pre>")
	}
}

Feedback Request

I would appreciate any feedback on this concept. If you think this is a good approach, please feel free to reach out with ideas for optimizations and other improvements to this API.

[Nemanya8]

Continuation of #2753 (comment)

To support Markdown features like bold, italic, and strikethrough, a simple approach would be to implement individual functions for each feature, passing the affected text for processing. While this method is easy to implement and computationally inexpensive, it relies heavily on string concatenation, which can be inelegant:

func (html *HTML) Bold(text string) string {
	return "<b>" + text + "</b>"
}

Usage example:

md.P("This is a sample paragraph " + md.Bold("in markdown."))

A more elegant solution is to adopt a Sprintf-like approach. Although this method is more complex and computationally intensive, it allows for more flexibility. Instead of manual string concatenation, we can scan the entire string and replace special symbols with their corresponding HTML tags.

md.P("This is a sample paragraph **in markdown.**")

[leohhhn]

@Nemanya8

Thanks for the proposal. I would advise you create a PR with your library, and try to use it in some of the already existing realms in the examples folder. For example, you can try to make the r/gnoland/home realm better (mainly it's code readability); it's using the old p/demo/ui library, which is quite hard to use & read. r/gnoland/home is the realm that powers the gno.land home page.

With this, we can see the practical side of your code. You can choose another existing realm as well, or choose to make your own, showcasing the potential of your proposal.

There, we can also leave comments and discuss specifics of the code, such as readability, performance, etc.

[moul]

Please open a dedicated issue or pull request with your example so we can comment on it. Be sure to reference your issue or pull request here.

I have comments to provide, but I don't want to clutter this issue further.

[moul]

Note: we're not looking for a Markdown to HTML library or an HTML framework. We are seeking a Markdown framework that allows us to write idiomatic Gno and generate Markdown.

[alexiscolin]

Here are some thoughts on this requirement. Since a library that renders markdown from a go abstraction might be not enough to be considered a complete framework, here is a non-exhaustive list of ideas inspired by other UI frameworks (Hugo, Pug, Handlebars...). These ideas are meant for brainstorming and discussion purposes only.

"What makes a good templating/UI framework for GnoWeb?"

This question is fundamental. However, do we need all of these features for the render function? And do we want to "break"/"update" it at this point? Many may be overkill or out of scope, but they came to mind when we mentioned a UI framework. cc @gfanton @leohhhn

Note

Disclaimer: Not all of these features or syntax suggestions are intended for implementation. Some may not fit our current scope, and others might not be appropriate. This is just a starting point for discussion to better understand the framework's boundaries/definition.

Key Features for an UI Framework

1. Powerful Templating Engine

   • Supports Variables, Loops (range), Conditionals, and Includes: Enables dynamic content generation (eg: update md display depending on md content)? (question, do we need it as we don't support html and pages or would it be overkill?)
   • Integrates data fetched or computed from various functions seamlessly.
   • Pipe Modifiers (Similar to Hugo): Facilitates inline formatting and transformations (e.g., formatting dates, converting text to uppercase etc)?
   • Tests

2. Dedicated Functions for Markdown Elements as presented in various PRs related to this issue.

   • Abstract Markdown Syntax: Provides functions like Header(level int, text string), Bold(text string), Link(text, url string), and List(items []Element) to eliminate manual Markdown syntax.

3. Data Binding and Integration

   • Seamless Data Integration: Facilitates passing complex data structures from multiple functions into templates.

4. Component Reusability

   • Reusable Components: Encourages creating components for common Markdown structures (e.g., tables, alerts). For a Design System to come.
   • Need for a Mixin-extends (eg. Pug) / Partial-Block (eg. Hugo) system, or may be too much for md and overlapping what we can already do?

5. Extensibility & Security

   • Custom Functions and Components: Supports adding new functionalities through custom functions or plugins.
   • By going further, we can imagine custom plugins such as i18n, styling, ASCII diagram generation...
   • All with security first in mind (sanitizer, scaper, whitelisting...) !

6. Separation of Logic and Presentation (already possible, but may be helped with this template)

   • Maintainable Codebase: Keeps business logic separate from Markdown presentation, enhancing readability?

7. Simplified Syntax

   • Intuitive Function Calls: Developers use clear/standardized function calls and templates.

Benefits

Improved Readability: Cleaner and more understandable code for generating Markdown.
Enhanced Productivity: Focus on content and structure without worrying about Markdown syntax.
Maintainability: Easier to manage and update complex documents.
Consistency: Ensures uniform formatting across different parts of the document.
Flexibility: Allows inline data transformations using pipe modifiers.
Security: Ensures all input and output are secure

What it may look like

What it may look like as Framework (minus some templating system feature such as mixin/partial that would create reusable contents/structures ...), but you can imagine:

Render function could be used with Templating System + Ui Markdown Functions OR/AND native Markdown.

package main

...

// Functions providing data
func introSection() string {
    return "We’re building gno.land, the leading open-source smart contract platform..."
}

func discoverLinks() md.Element {
    return md.List([]md.Element{
        md.Link("About", "/about"),
        md.Link("GitHub", "https://github.com/gnolang"),
        md.Link("Blog", "/blog"),
        md.Link("Events", "/events"),
        md.Text("Tokenomics (soon)"),
        md.Link("Partners, Fund, Grants", "/partners"),
        md.Link("Explore the Ecosystem", "/ecosystem"),
        md.Link("Careers", "https://jobs.lever.co/allinbits?department=Gno.land"),
    })
}

...

// Functions for pipes (These ones are genenric and may could be embedded in the Ui lib itself)
func FormatDate(format string, date time.Time) string {
    return date.Format(format)
}
func ToUpper(text string) string {
    return strings.ToUpper(text)
}

...

// Render function could add Templating System + Ui Markdown Functions OR/AND native Markdown.
func Render(_ string) {

// Define the template with placeholders, control structures, and pipe modifiers 
// OR directly at root of the function?
   const homeTemplate = `
# Welcome to gno.land

Published on: {{ .Date | FormatDate "Jan 2, 2006" }}

{{ .Intro }}

{{ Jumbotron .DiscoverLinks }}

### Latest Blogposts
{{ range .BlogPosts }}
- [{{ .Title }}]({{ .URL }})
{{ end }}

---
### Explore New Packages and Realms
{{ range .Packages }}
{{ Header 4 .Name | ToUpper }}
{{ range .Links }}
- [{{ .Text }}]({{ .URL }})
{{ end }}
{{ end }}
`
...

Generated Markdown:

# Welcome to gno.land

Published on: Apr 27, 2024

We’re building gno.land, the leading open-source smart contract platform...

[Jumbotron Content Here]

### Latest Blogposts
- [Post 1](/blog/post1)
- [Post 2](/blog/post2)

---
### Explore New Packages and Realms
#### PACKAGE 1
- [Link 1](#)
- [Link 2](#)

#### PACKAGE 2
- [Link A](#)
- [Link B](#)

---

Do you think this Framework features would effectively integrate with our current Render function and simplify our Markdown generation process? Is it too much? Maybe some ideas are good/bad, maybe you have other ones? For the framework definition and/or the application. Finally, what makes a good templating/UI framework for GnoWeb and what do we need?

Looking forward to your thoughts and feedback!

[moul]

Several aspects of this proposal excite me, particularly the text/template concept.

However, I believe the goal of the competition is to present multiple opinionated proposals. Ultimately, usage will determine the best ones, not me or the core team.

[thanhngoc541]

Besides Markdown, I've developed a UI components package designed to enhance UI designs. #2947
I would love to hear your thoughts and feedback!

[gfanton]

@thanhngoc541 your framework in #2947 looks pretty cool, but unfortunately, we are not looking for an HTML framework. As gnoweb should not support HTML syntax at some point (and i mean really soon), we want people to stop using HTML until that restriction has been introduced and enforced. Even if I know you were thinking more to an alternative, we cannot introduce this kind of framework until then.

[thanhngoc541]

I've developed another MDUI package designed to enhance UI designs using markdown. #2976
Looking forward to your feedback!

[salihdhaifullah]

Hi @moul, i have created this markdown utilities package, if you think it's a good fit for the use case i can port it to gno.land

[leohhhn]

@salihdhaifullah

You haven't provided Gno code; this is go code. Please make a proper PR with Gno code that's tested. Gno doesn't support generics.

[gfanton]

As mentioned in #2976:

I'm wondering if it would be better to have those libraries either in the user namespace or in a dedicated directory until a good one starts showing up.

Like for GitHub, people should generally start building their own libraries in their own namespace, and at some point, if the library is good enough by adoption and usage, we can think about moving it into a more official place.

Additionally, we could use the demo/ui package to reference all of them and potentially have some kind of poll to rate them as part of the competition process?