search

dwyl / product-roadmap

:globe_with_meridians: Because why wouldn't you make your company's product roadmap Public on GitHub?
46 stars 6 forks source link

Features of Docs/CMS #49

Open nelsonic opened 3 weeks ago

nelsonic commented 3 weeks ago
LuchoTurtle commented 3 weeks ago

In the context of Nextra, here's what I think it's doable:

  • [ ] 💻 Run locally with minimal overhead (no multiple containers or thousands of dependencies/devDependencies) 🏎️

This one's subjective but if you're speaking about the time-to-compile when running pnpm run dev, it's understandable the frustration. It depends on the features you want to add, but there's going to always be overhead the more features you want.

  • [ ] 1️⃣2️⃣3️⃣ Version Control - preferably git (GitHub, Gitlab, etc.)

Nextra integrates well with Git, GitHub, and GitLab for version control.

  • [ ] 📚History of changes; check how good Git is at showing the changes made.

With Git, I'm keen to believe that the diff and checking the history of change with Git is robust enough to keep track of.

  • [ ] 🔐 Authentication + Role Based Access Control

This requires additional implementation. Because Nextra is built on top of Next.js, it should be possible to integrate with https://next-auth.js.org/, as Nextra is based off Pages Router. Role-based access control is possible by conditionally rendering content. However, since the site is statically generated and incrementally pre-fetched, it is possible people can see docs in the final bundle.

  • [ ] 🙈 Private content based on Auth/Role

Same as above, it would need custom implementation or integration with a third-party solution. This may change with the release of v3 -> https://github.com/shuding/nextra/pull/2245.

  • [ ] 🖼️ image uploads with automatic optimisation, compression captioning & CDN. (Saves to /assets by default but can easily be served from CloudFront/CloudFlare)

Image optimization can be achieved using Next.js' built-in features that Nextra leverages.

  • [ ] ✍️ WYSIWYG Editor

Nextra does not have a built-in WYSIWYG editor, markdown is used instead. I don't believe this is possible, it's too much of a shift.

  • [ ] 📝 Collaborative online+realtime editing with conflict resolution. (V2)

Not supported out of the box; would require integration with a collaborative tool. But even then, Nextra is markdown-based, I don't think this can be easily added at all.

  • [ ] 📺 Embed content from other sources; video, images, iframe.

Nextra supports content embedding through markdown and custom components. So this should be doable.

  • [ ] ✅ Valid HTML + 100% Accessibility

Nextra generates valid HTML, and accessibility features can be implemented using best practices. We can further customize accessibility with custom components if needed (though reaching the 100% Accessibility mark may prove to be difficult because some code is invariably un-changeable behind Nextra's source code.

  • [ ] 🔦Great SEO by default; no config or plugin required.

SEO optimization is possible using Next.js features and Nextra's default settings. Because Next.js (and consequently, Nextra) is SSR-first as default, this is good for SEO.

  • [ ] 📈📊 Analytics built-in (zero config). Page load time, dwell, scroll height & links clicked.

Nextra doesn't have built-in analytics, better to integrate with https://github.com/plausible/analytics or some other self-hosted alternative.

  • [ ] 💯Visible view counter on page (or only visible as overlay based on Role).

Not out-of-the-box, but should be possible. By using a websockets strategy and a simple Elixir backend, we should keep track of the live number of visitors in a given channel/topic and open a connection with Next.js. We already did this with Plausible, so it's possible.

  • [ ] 🏷️ LLM enhanced keyword tagging for better Search!

I'm not sure what this means. You mean optimizing SEO through keyword tagging to LLMs can crawl the site more easily for index? Or do you mean using an LLM to search the content better within the site? Since Nextra uses FlexSearch...

https://github.com/shuding/nextra/blob/01535e2c53b001ceb9d5f19abab88d2707442a61/packages/nextra-theme-docs/src/constants.tsx#L300

... it should be possible to integrate with another client-side search alternative that leverages LLM. Or server-side, even (it is possible with Algolia).

  • [ ] 🔍Search with history. Both anonymous and personal; i.e: list my search terms and results.

I feel like the only way of achieving this is actually saving the history of changes per user on a database and put it behind an indexing/searching service (much like Algolia or any other) to fetch this information and return to the user. Nextra is a frontend application, so this feature can probably be added as a custom component somehow.

  • [ ] 🌏 i18n Translation: machine-driven + human reviewed/enhanced. Automatically updated when primary content is changed/added. Must be tested with right-to-left languages e.g. Arabic

Nextra supports i18n, but machine-driven translation and real-time updates would need custom integration that I think are not easily implementeable.

  • [ ] 📱 Mobile first. Fast-loading static content. (Analytics script loads after fully rendered)

Nextra provides fast-loading static content suitable for mobile-first design with Next.js optimizations as foundation.

  • [ ] 🤲 Must work without JavaScript on an e-reader (yes, this means no client-side analytics, but it’s <2% of views and we can still log the access)

Nextra can work without JavaScript for basic content delivery, so it should be suitable for e-readers.

  • [ ] 🖥️ Progressively Enhanced experience on large screens/devices.

Nextra's (powered by Next.js) responsive design supports progressive enhancement on larger screens.

  • [ ] 🪄 inline code examples where relevant (e.g: LiveBook/Jupiter Notebook)

Code examples can be embedded using markdown, but live execution would require additional setup (this is obviously beyond the supported highlighting provided by Nextra).

  • [ ] ⌨️ Keyboard shortcuts for common actions: search, navigation, etc.

The search component is an example of this is possible ( ⌘ + Z highlights the search bar to write ). So it should be possible to work on top of Nextra to override actions like navigation (e.g. https://www.danstroot.com/snippets/nextjs-hotkeys).

PDF generation requires a separate tool or custom script, either client or server-side (e.g. https://stackoverflow.com/questions/70931969/how-can-i-export-a-nextjs-page-as-pdf).

  • [ ] 🪄 Theming: excellent default theme; light, dark & high contrast. Easy theming e.g. adopt Wordpress theme format.

Nextra supports custom theming with light and dark modes. More complex theming needs additional configuration. We can make a theme on our own, but that takes a lot of work.

  • [ ] 🔗 link sharing, shortening & click-through tracking.

Not built-in; would need to integrate third-party services.

  • [ ] ⛓️‍💥 automatic check all links (internal & external) before publishing new version.

Link validation requires additional tooling like remark to lint all .mdx files.

  • [ ] 😊👍❤️🦄😕 reactions/emojis to content

Requires custom implementation for reactions/emojis, which should be doable with a back-end service and a custom remote component with Nextra -> https://github.com/shuding/nextra/tree/main/examples/swr-site/pages/remote.

  • [ ] 💬 Feedback button/form; zero friction.

Can be added with custom components or third-party integrations.

  • [ ] 🗺️ Sitemap and Robots.txt

Nextra can generate a sitemap and configure robots.txt using Next.js features.

  • [ ] 🤖JSON by default (where relevant)

Docs are Markdown-based, not JSON-based. Not doable.

  • [ ] 🛜 RSS for posts/news/updates

RSS feed generation is possible with custom setup or plugins. It should be possible to work on top of Nextra as a Next.js app -> https://dev.to/promathieuthiry/creating-an-rss-feed-in-your-nextjs-project-20em

nelsonic commented 2 weeks ago

@LuchoTurtle definitely wasn't expecting you go through the list 📝 and add comments for the implementation feasibility in Nextra ... 💬 It's good that you deep knowledge of Nextra/Next.js 👌

For me, the fact that Nextra doesn't have a backend by default is a total deal-breaker. 🙅 Don't get me wrong, it's useful constraint in aiding adoption from people who just want a static site generator ... But I want to have an optional backend so that I can build useful features (auth, rbac, colab) and track events! e.g: what content is being viewed and by who. 👤 Without having to rely on a 3rd Party service like Google Analytics or Plausible... We have worked around the Analytics feature by self-hosting Plausible Community Edition. But having Analytics separate from the docs means no overlay heat maps or interesting contextual insights, at least not without having to write a ton of extra code. 🧑‍💻 ⏳

Linking to the v3 PR of Nextra https://github.com/shuding/nextra/pull/2245 just proves my original point

image

A year-old draft PR with no description, hundreds of commits but no linked issues is my idea of hell! 😢 There's clearly a lot going in the PR with 665 Files changed ... Too much for a busy person to go through in a reasonable amount of time. ⏳

Being forced to have multiple _meta.json files spread across the project has been a annoying: https://github.com/dwyl/nextra-demo/issues/4#issuecomment-2321990832 this could easily have been avoided. Also the option to "hide" a page doesn't work. 🙃

The thing I would still like to implement in our Nextra project which is reusable elsewhere is "Custom Analytics Events" ... more on that soon. 😉