publishing RFC #2
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| --- | ||
| Start Date: 2020-07-27 | ||
| RFC PR: (leave this empty) | ||
| Foam Issue: (leave this empty) | ||
| --- | ||
|
|
||
| # 0001 Publishing | ||
|
|
||
| This RFC is more an umbrella covering the entire publishing story in order to discuss the architecture as opposed to implementation details. | ||
|
|
||
| ## Summary | ||
|
|
||
| - Replace Jekyll publishing by one (or more) [Gatsby](https://gatsbyjs.org) themes (one for each use-case) | ||
|
There was a problem hiding this comment. Would replacing be the right word here? Given Foam's core principles, would it be too hard for us to be SSG-agnostic? Surely, we can have recommended setups (just like we have extensions), but I say we atleast have 2-3 "official" foam templates (official naively means here, setups that are under the @foambubble umbrella) There was a problem hiding this comment. You can obviously use any SSG that you want - but I believe that we need to focus on creating a really good experience and that means picking a SSG. If you are technical enough to have a strong about it, you can probably use any you want on your own. There was a problem hiding this comment. I can appreciate both sides to this. Personally, I'm looking forward to using Gatsby - it seems to be considerably more powerful than the other SSGs - so I'm highly grateful for mathieus' focus on it as I am NOT technical enough to do a good job with any of the SSGs. He only has so much time, so I'd encourage him to focus on Gatsby (or do whatever he wants!). Yet, if there's anyone who wants to use a different SSG, there's no reason that they couldn't build and share a recipe/implementation for it. To that extent, perhaps dont "replace", but rather say that the purpose of this RFC is for the development of Foam-friendly Gatsby themes? It'll be the default insofar as it is the only one being currently developed, but its important not to turn away anyone who might be keen for Jekyll or anything else. There was a problem hiding this comment. You're totally right: we are going to replace the default way to publish a Foam workspace (from Jekyll to Gatsby) for the reasons mentioned in the Motivation section, but you can still use any SSG if you want to, knowing that it won't be officially maintained (and so might be missing features developed by Foam like backlinks, block embeds, etc.) |
||
| - Support an array of hosting solutions (GitHub pages, Netlify, etc.) by providing files to drop into a Foam workspace (`.github/workflows/publish.yml`, `.netlify.toml`, etc.) | ||
mathieudutour marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Provide a recipe to customize a theme | ||
| - Provide a recipe to use other Git providers | ||
|
|
||
| ## Motivation | ||
|
|
||
| One of the goals of Foam is to make it easily to share your thoughts. That imply a way to publish a Foam workspace on the internet. | ||
|
|
||
| At the moment, that goal is fulfilled by leveraging the GitHub built-in publishing system: Jekyll + GitHub pages. While it works great for simple websites, we feel that we are going to rapidly outgrow it if we want to surface backlinks, block embeds, etc.. We also want to decouple the GitHub Foam template from the publishing part. That means that the code source of the website shouldn't be bundled but instead we only include a configuration file if needed. | ||
|
|
||
| Gatsby is a popular static website generator (SSG) built on React and GraphQL. It provides a way to share functionalities (a ["theme"](https://www.gatsbyjs.org/docs/themes/what-are-gatsby-themes/)) while retaining full control over the customization if the user wants to (see [Shadowing a theme](https://www.gatsbyjs.org/docs/themes/shadowing/)). Building a Gatsby project produces a `public` folder ready to be deployed on any static hosting provider, making it the perfect candidate for an extensible system with good defaults and a huge community to help. Gatsby themes can use any Npm packages, meaning we will be able to leverage the different packages made by foam-core to extract information needed from a Foam workspace. | ||
|
There was a problem hiding this comment. I'm particularly interested in having recipes for the customization of themes, and I would imagine that most people would be as well so that they can make the theme "their own" with whatever layouts and features they want. I know that Gatsby has fantastic documentation, but I would assume that any Foam-specific themes (especially having integration with graph, MDX etc...) would make it more complicated. If there could be both detailed recipes as well as well-documented/commented code, that would be wonderful! |
||
|
|
||
| GitHub pages is still a great hosting solution for a simple way to get things online. It will stay the default way of publishing a Foam workspace but we want to support other hosting solutions as first class citizens. Each of them have different pros and cons. The main advantage of GitHub pages is that it's by GitHub so you don't need another account to deploy something. The main disadvantage is that it is not available for free users on private repos. Luckily it wouldn't be too complicated to support multiple hosting solutions by using Gatsby. | ||
|
|
||
| ## Detailed design | ||
|
|
||
| - A repo for each Gatsby theme (`gatsby-theme-foam-blog`, `gatsby-theme-foam-digital-garden`, `gatsby-theme-foam-team-doc`, etc.). Each theme should be discussed in follow-up RFCs. | ||
| - Each theme should try to have consistent options so that trying a theme is as simple as changing its name in the configuration file. | ||
| - A repo to host hosting configuration | ||
|
|
||
| ## Drawbacks | ||
|
|
||
| ## Alternatives | ||
|
|
||
| ## Adoption strategy | ||
|
|
||
| ## Unresolved questions | ||
|
|
||
| - Using a theme means adding a `package.json` and a `gatsby-config.js` files to a Foam workspace. | ||
| - Shall it be included by default in the template? | ||
| - If so with what theme? | ||
| - Using a hosting solution means copy pasting the configuration files in your repo | ||
| - Could this be automated with a cli `npx foam setup-host netlify`? | ||
|
There was a problem hiding this comment. I like the idea of a CLI! This does raise the concern of working with non-technical users, but with a CLI in place I suppose extensions could provide a GUI to cater for that? There was a problem hiding this comment. Yeah probably. But I was thinking it’s a one time step. So it might be fine asking them to run something in a terminal? Especially if they need to clone a repo already, right? There was a problem hiding this comment. Yes true, and that thought crossed my mind too. It's true that if somebody is looking to host a website that it's safe to assume a certain level of technical ability! There was a problem hiding this comment. I have a higher technical ability than 99.9% of people, yet still find some of this stuff daunting at times. But I don't think a CLI (or anything really) is too onerous if it is accompanied by quality documentation. There was a problem hiding this comment. Otherwise we can provide a "manual" way to do it: download the files and add them to your workspace. But I'm pretty sure some people will put it in the wrong space or if it needs a hidden folder they won't know how to create one and so it will end up being potentially more difficult There was a problem hiding this comment. What is also stopping us from integrating this in the Foam extension itself, like |
||
| - Shall the deployment to GH pages be included by default in the template? | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I imagine there are 2 things we are covering in this RFC that are related but maybe not necessarily coupled:
Would it be helpful to split these two aspects?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Indeed, there are 2 things, and I wanted to cover them together at a high level to see how they can fit together. As mentioned in the RFC, follow-up RFCs should be opened for specific implementations
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Understood, I guess I was confused because I saw that it also includes one specific implementation (replacing jekyll w/ gatsby), and looking again at Sanket's comment (whom for some reason I seem unable to @mention) I believe it is along the same lines.
Anyhow, I like going for gatsby over jekyll!