web3-storage
Content management layer for blog
The blog (#1415) is largely available to ship, however, any edits must be made directly to the markdown files.
Benefits
A content management system would make the process of publishing content more streamlined, as well as put the focus on the writing, rather than editing posts in a code editor (wysiwyg editors would display formatting immediately, rather than having to wait for build previews, or building the website locally).
Type of CMS
(Edited, see my second comment in this issue for more information)
~~It's probably best not to fully abstract blog content from Github. For this reason, most external CMS systems (i.e., where the content would live somewhere else and then need to be pulled into the site during run time or build time) aren't ideal.~~
~~The ideal solution IMO is an external service that functions as a layer on top of Github, enhancing the current workflow.~~
Ideal flow
The path with the fewest hurdles but the most amount of gain looks something like this
- A CMS that's integrated with the current site and works with markdown
- Author logs in to the CMS service which enables them to edit, remove, or create a blog post
- Once the author is satisfied with content edits, they save the page
- ~~Saving the page creates a commit or a PR in this Github repo~~
- ~~Blog content is shipped on merge, just like anything else in the repo~~
(Edit: Added strikethroughs to some areas because we do want to fully decouple the blog content from the Github Workflow)
@dchoi27 does this approach make sense to you?
If so, two good candidates are:
They're from the same company, and Tina is the successor of Forestry.
- Forestry is more of a traditional CMS UI (the blog post editor looks like a markdown-compatible word processor)
- Tina allows for "live editing" in a page-builder like interface (you can see what the content looks like in the actual Web3.Storage website design), however, it's still in beta.
Also open to other options, like Netlify CMS. I've worked with Forestry a good bit and it's pretty straightforward to integrate.
blog.ipfs.io has been using forstry.io for a good while now, so that's a +1 for it. see: https://github.com/ipfs/ipfs-blog#for-post-authorseditors
Update to requirements: I got some clarification to the requirements here. The objective is to include a CMS layer such that it IS fully decoupled from the Github workflow. I've edited my original issue content with some strikethroughs.
Updated requirements
- The blog CMS should be fully decoupled from the Github workflow
- i.e., when a post is published in the CMS, its content is shown directly on the site without requiring any PR's, merges, etc. in Github
- Therefore the blog must get the content from an endpoint, presumably during client-side runtime (the user's browser hits an endpoint somewhere)
- It's also possible to populate the blog from an endpoint as part of the build process
Considerations
There are now some net new considerations that should be discussed.
Approach
Decoupling from Github entirely means that NextJS is no longer the source of truth for (blog) content. Consequently, content will not be built directly into the static site. This means that we need to determine some architecture, i.e., how (and when in the sequence) content is added.
-
Runtime
- Content could be requested from an API of a CMS client-side
- When a blog page is loaded, some requests will be made, and the content will be formatted and displayed in real time
- Search engines, and other entities that capture web pages, won't pick up the content
- The CMS would need to support some endpoints for searching blog content
- A refactor of the blog will probably be required (depends on solution)
- This approach would mean the blog is fully decoupled from Github: when an update to the CMS is made, the content shows up on the website immediately
-
Build time
- Alternatively, content could be requested from the CMS API when the site gets built by the CI/CD
- A script would retrieve each blog post and inject the content into the static site's resources
- This approach would be search engine friendly, because content would still live in the export of the static site
- A refactor to the blog would either be minor or not required at all
- Build time would take a little longer
- However, content would only update when the website is released to production, so this won't be fully decoupled from Github, only the PR process
- Alternatively, content could be requested from the CMS API when the site gets built by the CI/CD
-
Hybrid
- An alternate solution could involve both options:
- The blog content is injected during the build
- And some API calls also check if a post has newer content available
- If a newer post is available, the browser gets that post
- This option is more work, because it's both options rolled into one
- Is SEO-friendly while also fully decoupled from the Github workflow
- An alternate solution could involve both options:
Note: An approach I'm not considering here is using a totally different web stack for the blog on a subdomain (e.g., a separate repo, or a standalone Wordpress site)
Constraints
- Currently, the blog is written in Markdown and follows the Frontmatter specification (a metadata header followed by standard markdown)
- Some solutions might require a refactor of the blog as it stands right now, especially to support blog search and filtering
CMS Options
With that said, we can go over some CMS options
Self-hosted, headless JS CMSs
I've used the first two in the past, but they would need to be run somewhere: they're open source and headless.
CMS services that offer a REST API
- Ghost (using their content API available with Pro accounts)
- Contentful
Excluded from evaluation
I've excluded two types of CMS's here:
- Those that use an entirely different non-JS stack (e.g., Wordpress, Pico)
- Those that require integration into a git workflow (e.g., Forestry, Tina, Netlify CMS)
If anyone has any others to add that would satisfy the requirements feel free to comment or add to the lists.
Per decision made by Mikeal, we'll be using NetlifyCMS across the board (in NFT & Web3 sites and blogs). More details regarding approach and decision are in this doc https://www.notion.so/Content-Release-Cycle-Improvement-Rec-2656dcf910a94b33881b973ec4d6f1ca We'll have a PR on the NFT side soon that you can follow to align the wip web3 blog to support this approach.
Per decision made by Mikeal, we'll be using NetlifyCMS across the board (in NFT & Web3 sites and blogs). More details regarding approach and decision are in this doc https://www.notion.so/Content-Release-Cycle-Improvement-Rec-2656dcf910a94b33881b973ec4d6f1ca We'll have a PR on the NFT side soon that you can follow to align the wip web3 blog to support this approach.
@JeffLowe ah okay, so we'll be making an additional repo for the content, yes? Any idea if the NFT.Storage and Web3.Storage content repos will be combined into a sort of content monorepo? Or will there be multiple content management repos?
Likely best to have separate repos one for web3 and one for nft. We're investigating whether it makes sense to have one segmented intance...but likely best to separate web3 from nft content.
Original description scope for archival purposes: The blog (#1415) is largely available to ship, however, any edits must be made directly to the markdown files.
Benefits
A content management system would make the process of publishing content more streamlined, as well as put the focus on the writing, rather than editing posts in a code editor (wysiwyg editors would display formatting immediately, rather than having to wait for build previews, or building the website locally).
Type of CMS
(Edited, see my second comment in this issue for more information)
~~It's probably best not to fully abstract blog content from Github. For this reason, most external CMS systems (i.e., where the content would live somewhere else and then need to be pulled into the site during run time or build time) aren't ideal.~~
~~The ideal solution IMO is an external service that functions as a layer on top of Github, enhancing the current workflow.~~
Ideal flow
The path with the fewest hurdles but the most amount of gain looks something like this
- A CMS that's integrated with the current site and works with markdown
- Author logs in to the CMS service which enables them to edit, remove, or create a blog post
- Once the author is satisfied with content edits, they save the page
- ~~Saving the page creates a commit or a PR in this Github repo~~
- ~~Blog content is shipped on merge, just like anything else in the repo~~
(Edit: Added strikethroughs to some areas because we do want to fully decouple the blog content from the Github Workflow)