publishing RFC #2
Conversation
|
|
||
| ## 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.)
| - 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 foam-janitor does? 🤔
|
|
||
| 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!
| Foam Issue: (leave this empty) | ||
| --- | ||
|
|
||
| # 0001 Publishing |
There was a problem hiding this comment.
I imagine there are 2 things we are covering in this RFC that are related but maybe not necessarily coupled:
- generating a static website out of a foam (gatsby, jekyll, ...)
- publishing a generated site to a hosting provider (netlify, github pages, ...)
Would it be helpful to split these two aspects?
There was a problem hiding this comment.
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.
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!
🖼️ Rendered