Support for blog home pages (or any catalog-like home pages)

[olayway]

Shaping

Situation

Currently, if you want to have an home/index page for your blog (or docs, tutorials, recipes etc.) in your DataHub Cloud site, you need to create a markdown README.md/index.md page - using markdown syntax only, probably with a list of links to other pages.

Problem & Opportunity

Limitations:

• a raw markdown list of links doesn't look appealing,
• requires manual updates each time a new blog post (doc page, tutorial etc.) is created,
• requires manual metadatainclusion (e.g if you want to display dates or authors you need to write them somewhere next to your link).

Opportunities:

• Allow users to enhance their sites by creating any number of index pages with the blog/catalog layout, in different content directories.

Solution

General Solution Idea

Develop a flexible blog/catalog layout that allows users to apply it to any page by setting specific frontmatter fields in their markdown files. This will enable users to create catalog-like pages, such as /blog, /tutorials, /events, and more.

Implementation Analysis

1. Create a reusable catalog layout.
2. Frontmater configuration:
   • Introduce a layout: catalog frontmatter field to specify the use of the catalog layout.
   • Add a catalogDir: "/path" frontmatter field to define the directory whose markdown files should populate the catalog layout. By default, this could be the parent directory of the file.
3. Create an API endpoint for fetching a list of files (with the needed metadata) included in the catalogDir.
4. In the [[...slug]].page.tsx:
   • fetch the index page metadata
   • if layout: catalog fetch files within the catalogDir from the API
   • instead of rendering MdxPage component, render the blog layout/component

Metadata fields to display:

• title
• description
• date (if provided, order by it; otherwise sort by title and hide the date element)
• authors
• (future) tags

Flowershow compatibility (Is this necessary?)

To maintain compatibility with Flowershow config file, we could also add support for its blogDir, with the following exceptions:

• blogDir would no longer default to /content/blog
• /blog path would be rendered as a blog index page only when blogDir is specified.

=> If a Flowershow user relied on the default blogDir value and wants to have his blog at the usual /blog, he'd have to explicitly set blogDir: "/blog" in the config.json file.

Design

Use this Tailwind component: https://tailwindui.com/components/marketing/sections/blog-sections#component-71451303bfa569c95e0f084e67da54f2

Rabbit holes

No-goes

• don't enforce /blog path to be always used for the blog index page (as it is in Flowershow)

Appendix: Flowershow implementation considerations

In Flowershow there is only one special /blog page that displays all the markdown files from the blogDir configured in the config.json.

The problem with this approach is that /blog page is always going to use the special "catalog"/"blog" layout. There is no way to:

• opt out of having /blog path use this template
• having more pages like this, e.g. /tutorials, /events, /recipes

I'd suggest making this more flexible and allowing people use this blog/catalog layout on any page they want.

Solution:

• build the catalog (or blog or other name) layout
• allow people to use it by setting layout: catalog frontmatter field on virtually any page they want
• allow people to pick the directory that should be used to populate the layout, e.g. catalogDir: "/tutorials" frontmatter field (by default it could be the parent directory of the file)

This way users wouldn't be bound to /blog path only. And you can have different catalog pages like that, e.g. /blog, /tutorials, /docs, /events ... in a single site.

Note in Flowershow we used to also have peopleDir that would point to a directory with markdown files holding information about content authors, that would then be displayed on blog pages.

[rufuspollock]

@olayway great outline. I think we could do a bit more shaping here to flesh this out and then look at this. Definitely something we want for each the DataHub blog.

Quick thoughts:

• Is there some way to use our markdowndb and it's query language to allow selecting posts (or is this making things complex? probably ...)

[olayway]

Is there some way to use our markdowndb and it's query language to allow selecting posts (or is this making things complex? probably ...)

I wouldn't consider using markdowndb until we have a "proper" index of site files. Currently it's still just a JSON in a files column.

[olayway]

@rufuspollock I've added the shaping to the description. Please take a look and let me know what you think.

[rufuspollock]

Acknowledging and wondering if we want to defer this on having a proper index of site files ... hmmm.