Developer FAQs for PortalJS

[luccasmmg]

A data portal is built with multiple features. We want to identify and list the most common ones and explain what is the easiest way to do them using PortalJS.

Acceptance

• A list of common features/outcomes users of Portal.js would want or need
• How to achieve them with either Flowershow or Portal.js or even just using standard NextJS, Tailwind, JS etc
  • Each one of those items needs to have a clear tutorial with preferably the least amount of code possible

Tasks

• Get a list of features with title question
• Prioritize based e.g. on likely importance to user and whether we have a solution
• v0.1 create howto pages for first 4-5 items e.g. /howtos/analytics and an index pages howtos which uses obsidian wikilinking to link to each page with a nice title e.g. [[analytics|How to add web analytics]]
• Sketch solutions (maybe just one or two as we can come back to this later)
  • Focus is on developers adding this
  • Bonus for adding "contributor" info i.e. discussion about how this implemented and potential changes
  • Bonus for adding "editor" info e.g. for people who run the portal but aren't developers
• Come up with recommendation for config stuff @6v5rryFoQBqA6oMVm1pNKw

Questions

• SSR vs SSG SSG since its just a tutorial

List of features

• Analytics: "How to add web analytics?"
• Page metadata for SEO "How to customize the page metadata e.g title, favicon?"
• Sitemaps "How to build a sitemap"
• Blog: "How to add a simple blog (markdown-based)?"
  • Index page
  • Blog Layout
  • Comments
  • Author pages "How to add author pages"
• Adding content:
  • "How to add markdown-base content pages"
  • "How to support rich content in your markdown including ...."
    • Math
    • Mermaid
    • Custom remark plugins
    • Tables of contents
      • Inline
      • LHS
  • "How to add content from an external CMS like wordpress?""
• Data Rich Documents: "How to have data rich documents with charts and tables?"
  • Charts
  • Maps
  • Tables
• Theming
  • Footer "How to add or customize the footer"
  • Navbar
  • Fonts and colors
• Forms
  • Contact forms
  • Newsletters

List of features

• Analytics including google ✅ Implemented on Flowershow
  • 1st part is pageview function exported from @flowershow/core: https://github.com/datopian/flowershow/blob/main/packages/core/src/utils/gtag.ts
  • 2nd part is using it in useEffect hook in pages/_app.tsx (but this could also be wrapped in a custom React hook that would be exported from core package or portaljs) https://github.com/datopian/flowershow/blob/df602b840dc3898142452921ed1558e2fdb276c8/packages/template/pages/_app.tsx#L69-L79
• Sitemaps for SEO ✅ Implemented on Flowershow; NOT a part of @flowershow/core but can be easily extracted
• Add to learn-example
• we have a script sitemap.mjs that generates the public/sitemap.xml file
  • depends on @flowershow/markdowndb package (if we extract it, we could make it independent on markdowndb = generic) https://github.com/datopian/flowershow/blob/main/packages/template/scripts/sitemap.mjs
  • can be run as part of a prebuild script in package.json
• Page metadata for SEO ✅ Implemented on Flowershow, but not part of @flowershow/core
  • we're using next-seo package
  • default SEO values are set in pages/_app.tsx based on values set in user's config.mjs file https://github.com/datopian/flowershow/blob/df602b840dc3898142452921ed1558e2fdb276c8/packages/template/pages/_app.tsx#L88
  • per-page SEO values are set in pages/[...slug]tsx based on page metadata passed to it from getStaticProps https://github.com/datopian/flowershow/blob/df602b840dc3898142452921ed1558e2fdb276c8/packages/template/pages/%5B...slug%5D.tsx#L21-L53
• Data rich document support: markdown rendering with charts and tables ****
  • Charts ✅ PortalJS
  • Tables ✅ PortalJS
  • Maps ❌ PortalJS
  • Mermaid diagrams ✅ our markdown renderer - not an importable component/lib yet
  • Footnotes ✅ our markdown renderer - not an importable component/lib yet
  • Linked headings ✅ our markdown renderer - not an importable component/lib yet
  • Maths ✅ our markdown renderer - not an importable component/lib yet
  • Table of Contents (inline) ✅ our markdown renderer - not an importable component/lib yet
  • Table of Contents (RHS) ✅ part of @flowershow/core
  • "My remark plugin here" ❌ Would be implemented on PortalJS? Depends on our approach. One option is to extract the DataRichDocument component and the parser to PortalJS and add extra plugins as a param.
• Blog
  • Blog post pages ✅ BlogLayout in @flowershow/core
  • Index pages ✅ We do have a BlogsList component in @flowershow/core that can be imported, but the user has to create the index page in /pages himself
  • Author pages ✅ Implemented on Flowershow just regular pages, linked to in BlogLayout
  • Comments / discussions ✅ part of ``@flowershow/core`
• Forms ❌ there's an implementation of newsletter form on the Flowershow website, but it's in a custom Hero component and just using netlify forms
  • Contact forms
  • Newsletters
• Home page usually with a bespoke design ✅ NextJS makes it possible, although we could have common and simple components e.g. hero
• Navbar ✅ part of @flowershow/core
  • How do i change the items in the navbar
  • How do I change the navbar completely?
• Footer ✅ part of @flowershow/core
• Content (blog or other pages)
  • from markdown ✅ Can be handled by MDDB and our md renderer
  • Or from external CMS ✅ Can be handled by Next.JS
• Search page for the whole site ❓ Search pages?
• DX
  • Bespoke components ❌ Components are not really customizable rn, but we can improve this
    • e.g. in this Card component (taken from tailwindui) we can optionally pass class names to it and its elements: https://github.com/datopian/flowershow/blob/main/packages/core/src/ui/Card/Card.tsx
  • Bespoke layouts ✅ We can use the Flowershow approach which allow for custom layouts + default layouts

Notes

Improvements to PortalJS

Currently, everything in the list can be done, since PortalJS runs over Next.js, but of course, that's too cumbersome.

The means to make those features available on PortalJS are:

• Extracting components
  • We are already exporting some components e.g. Table and LineChart
  • Any data component can be exported just the same
  • We also want to export the DataRichDocument component, so that data-rich READMEs can work with much fewer configurations, and that would come with the plugins e.g. footnotes, gfm, math, and, possibly, with LHS navigation and TOC. We could also allow to pass custom remark/rehype plugins to that component
  • The NavBar, Forms, Blog, Footer and so on, can be implemented, but a design will need to be agreed
• Creating a context provider
  • Read the configs file and setup:
    • GA
    • General SEO configurations
    • Sitemaps
    • MarkdownDB setup

Provider component

We could have a , similar to SessionProvider, ThemeProvider, etc.

This could be helpful to avoid copy/pasting code e.g. check if there's a GA token in the configs and setup the pageview call on route change events.

Specifically, everything in here could be done inside this provider and users would just have to wrap their apps inside it
https://github.com/datopian/flowershow/blob/main/packages/template/pages/_app.tsx --

E.g:

//  _app.js
import siteConfig from "content/config.js"

const MyApp = ({ Component, pageProps }: AppProps<CustomAppProps>) => {

return <FlowershowProvider config="config"> 
    <ThemeProvider>  //  Probably this could go inside the FlowershowProvider as well
      <Layout {...layoutProps}>  // ... and this
        <Component {...pageProps} />
      <Layout />
    <ThemeProvider />
  <FlowershowProvider />
}

[olayway]

@rufuspollock can we close this and open an issue for v2?

[rufuspollock]

@olayway why do we want to close and open a follow up - i'd want to at least keep overall list in one place so easy to follow what we have done. We can open subissues to this quasi-epic e.g. for recommendations for improvements to core libraries.

[olayway]

@olayway why do we want to close and open a follow up - i'd want to at least keep overall list in one place so easy to follow what we have done. We can open subissues to this quasi-epic e.g. for recommendations for improvements to core libraries.

Because I feel like this is usually what we do (open issue for V2 etc) 😅 But ok, let's leave this one.

[rufuspollock]

@olayway yes on this one it's a lot easier to see the progress because we are working through a specific list for now - i understand about often splitting especially as work flows across iterations. As i said we can have sub-issues for stuff like improvements to core libs.

[popovayoana]

@olayway @luccasmmg @demenech @anuveyatsu can someone update the issue? i just want to understand if we're still working on these items and if we're following the plan. thanks 🙏

[demenech]

can someone update the issue? i just want to understand if we're still working on these items and if we're following the plan. thanks pray

Hi @popovayoana . I'm not sure about the state so I'm going to leave it for @luccasmmg

[luccasmmg]

@popovayoana the current version of this is on https://portaljs.org/howtos but no work has been done on it for a few weerks, this issue is kinda of an epic so it will not get closed for the time being, but technically the first version of this has already been done.