docusaurus: the blog experience

[dovholuknf]

right now the blogging experience is all based on hashnode. it would be better to be able to:

• author a blog using docusaurus' blog feature
• use vercel to render PRs against the repo to solicit comments https://github.com/openziti/ziti-doc/issues/185
• once merged to main have hashnode import from the markdown in the blog (assuming jsx/mdx doesn't interfere with this and assuming image imports work etc... that's a big 'tbd')
• if possible have hashnode federate/promote/crosspost to other static host sites

[qrkourier]

I understand this would change the life cycle of a blog post to begin with a Docusaurus site hosted on Vercel.

It sounds like you're saying there's some GitHub magic built in to Vercel or Docusaurus or both that could enable new blog posts to trigger pull requests in GitHub. Is that accurate?

I understand that, later in the workflow, Hashnode might be able to ingest the post from GitHub and subsequently syndicate.

[dovholuknf]

It sounds like you're saying there's some GitHub magic built in to Vercel or Docusaurus or both that could enable new blog posts to trigger pull requests in GitHub. Is that accurate?

Hashnode is able to publish from a github repo. So technically I'd say it's hashnode that has the 'magic'. I also don't know if it'll work. Part of this issue is to identify if this flow will be successful

[qrkourier]

Making sure I understand the possible end result / Docusaurus blogging experience vision:

1. draft a blog post with Docusaurus running in a local development/preview server
2. Git commit the draft Markdown and share as pull request in GitHub
3. Vercel notices the GitHub event and renders the PR branch as a draft site
4. Collaborators review the draft site in Vercel and comment on the PR in GitHub
5. Committer merges the approved PR in GitHub
6. Hashnode notices the merge to main branch and posts to its blog

[dovholuknf]

That's the basic flow yes. Vercel or hashnode are implementation details ... The goal is to allow people to contribute with as little friction as possible. That flow seems like it would be a pleasure. I'm open to other ideas though if there's a better idea/flow

[qrkourier]

It sounds like this wouldn't stop anyone from continuing to draft posts with Hashnode if that's their preference and they don't particularly need the GitHub PR process.

In that case it would be up to Hashnode to contribute the Markdown source back to the GitHub repo. I seem to recall that is a feature of Hashnode, and that the WYSIWYG-to-Markdown conversion wasn't conducive to a PR process and that's what led us to consider alternative workflows like this.

If that's all correct then we would have both options for drafting posts:

1. start with Docusaurus-WYSIWYG-to-Markdown and go through the proposed steps to publish to Hashnode
2. start with Hashnode-WYSIWYG-to-Markdown and publish directly in Hashnode, allowing Hashnode to sync the Markdown back to GitHub without a PR

Accurate?

[qrkourier]

I think the next steps include figuring out how a single Git repo can be the source of truth for the Hashnode and Docusaurus blogs.

[qrkourier]

@dovholuknf

Goals and Notes

1. All blog posts are published in HashNode irrespective of how they were drafted. This provides a unified reader experience and SEO.
   • It's acceptable if HashNode syndicates some posts while others are canonical in HashNode.
   • To avoid SEO problems like a HashNode syndicated post ranking higher than the original post, it's essential that the canonical URL is indicated for syndicated (cross-posted, republished) posts. This can be set in the front matter of an post ingested as Markdown with HashNode's GitHub integration.
   • HashNode's GitHub integration ingests only Markdown files, and there are risks associated with this integration i.e., clobbering a post with the same slug without warning.
2. Enable blog authors to compose articles as Markdown w/ preview rendering.
   • Composing Markdown w/ preview is a forthcoming feature of HashNode.
   • HashNode employs bespoke Markdown syntax, e.g. img align, that would either break the Non-Hashnode preview or, best case, be ignored. This may have implications for syndication as well if the re-publishing platform imports the Markdown instead of rendered HTML, CSS, JS.
   • HashNode's GitHub integration doesn't provide a preview, so we'd need another way of rendering that Markdown before publishing.
   • Assets such as images must be hosted out-of-band, not with the post's Markdown source.
3. Enable blog authors to employ a web framework like React to generate their post's content dynamically.
   • This would be nice to have, but there's not an immediate need for it.
   • Can HashNode ingest HTML? For example, by scraping posts described by an RSS feed?