[Epic] Support for user site configurations e.g. setting title for project, or stuff that is in config.js in flowershow

[rufuspollock]

A first pass on this has been implemented.

Shaping

Preview Give feedback

1. Detail what features have been implemented (and not)
2. Detail what features have been documented
3. Identify any items we want to migrate across

Implementation

Preview Give feedback

1. Option to exclude files from publishing (or to include specific files) datahub#1242
   good first issue ✨ enhancement +2
   
2. Option to add social buttons in the nav bar / footer datahub#1243
   good first issue ✨ enhancement +2
   
3. Option to use own Google Analytics key datahub#1244
   ✨ enhancement +1
   
4. Dark / light theme datahub#1248
   UX/UI ✨ enhancement +2
5. Support for blog home pages (or any catalog-like home pages) datahub#1249
   ✨ enhancement +1
   
6. "Created by XXX" note in the footer datahub#1250
   good first issue ✨ enhancement +2
   
7. Option to disable page table of contents datahub#1251
   ✨ enhancement +1
   
8. Docs reference page with all the available config options documented datahub#1255
   📝 docs +1
   

Shaping

Flowershow config fields

✅ - supported in DataHub Cloud
❌ - not supported in DataHub Cloud
⬆️ - should be supported
🗑️ - not needed or not relevant

title ✅

Default SEO site title and default navbar title.

description ✅

Default site description.

logo ✅

Path to logo.

author & domain ❌⬆️

In Flowershow used in the footer like this (along with logo):

Would be nice to add but display in a slightly different form maybe.

Note: ignore domain. Not sure why we thought this was needed in the first place...

navbarTitle ❌❓

Detailed navbar title config.

interface {
    logo: string;
    text: string;
    version: string;
}

Note: leave out for now. Not sure why we thought this was so important to have it on top of title and logo config fields.

navLinks ✅

type NavLinks = Array<{
	href: string;
	name: string;
}>

showEditLink ❌⬆️

"Edit this page" with a link to GitHub file at the bottom of a page.

editLinkRoot ❌🗑️

Wouldn't be needed in DataHub Cloud, as the app knows which repo was the site built from.

showToc ❌⬆️

Currently shown by default.

showSidebar ✅

showComments & comments ❌⬆️

Would be nice to add but requires separate shaping.

interface {
	provider: "giscus" | "utterances" | "disqus";
	pages: Array<string>;
	config: any // provider-specific config object
}

content ❌🗑️

In Flowershow it's a configurable markdown content directory.
In DataHub Cloud we have content directory configurable through the config field in the dashboard / site creation modal = directly on the Site object.

avatarPlaceholder ❌🗑️

In Flowershow it's a custom avatar placeholder image.
I don't think this is needed and I'm not sure why we added it in Flowershow in the first place. I'd drop support for it in Flowershow as well.

blogDir ❌⬆️

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.

peopleDir ❌⬆️

In Flowershow it's a special directory with authors' pages, that include some information about them, like name, avatar. Used in the blog layout.

theme ❌⬆️

Basic light/dark theme toggle. Let's add back, but not a top priority. First let's focus on making the layout look really nice.

Note: ignore "toggleIcon" in DataHub Cloud for now

interface {
	default: "light" | "dark";
	toggleIcon: string;
}

analytics ❌⬆️

Google Analytics key. Easy to add.

social ❌⬆️

Let's add this back and make sure we support more than "github" | "discord"

type Social = Array<{
	href: string;
	label: "github" | "discord";
}>

nextSeo ❌🗑️

We no longer use next-seo, and we set page metadata based on title & description from the config.json, frontmatter and datapackage.

This is useful for self-hosted option but I wouldn't allow people changing entire SEO config in the Cloud version. Maybe on a premium version someday.

  nextSeo: {
    titleTemplate: "%s | Flowershow",
    description:
      "Turn your markdown notes into an elegant website and tailor it to your needs. Flowershow is easy to use, fully-featured, Obsidian compatible and open-source.",
    canonical: "https://flowershow.app",
    openGraph: {
      title: "Flowershow",
      images: [
        {
          url: "https://flowershow.app/assets/images/frontpage-screenshot.jpg",
          alt: "Flowershow",
          width: 1200,
          height: 627,
          type: "image/jpg",
        },
      ],
    },
    twitter: {
      handle: "@flowershow",
      site: "https://flowershow.app",
      cardType: "summary_large_image",
    },
  },

search ❌🚧

Shaping in progress https://github.com/datopian/product/pull/248

  search: {
    provider: "algolia",
    config: {
      appId: process.env.NEXT_PUBLIC_DOCSEARCH_APP_ID,
      apiKey: process.env.NEXT_PUBLIC_DOCSEARCH_API_KEY,
      indexName: process.env.NEXT_PUBLIC_DOCSEARCH_INDEX_NAME,
    },
  },

Used to be supported in Flowershow

contentExclude & contentInclude ❌⬆️

I think we lost support after switching from contentlayer -> mddb, but definitely useful, especially for PKM audience.

Moreover, in Flowershow single files can be excluded by setting isDraft: true in frontmatter.

showLinkPreviews ❌

I think we lost support after switching from contentlayer -> mddb. Not a top priority imo. Someday, maybe.