Selective publishing of pages of foam

[Sholanki]

Hi! I wanted to deploy my foam website on Netlify and I wanted to keep some of the pages private and the rest open to public. I could not find a way to do it on Foam.

[SanketDG]

If you are using https://github.com/foambubble/foam-template, can you try setting published in the frontmatter

[thisizkp]

Any idea how to achieve the same when using https://github.com/mathieudutour/foam-gatsby-template?

[Sholanki]

This is exactly my question.

[mathieudutour]

Could you open an issue on the gatsby-digital-garden repo? I'm sure we can find a solution

[Klaudioz]

That's is a great idea and I was thinking to include a tag like excluded because I'm thinking to publish almost everything and I want to protect very few private notes.

[brentjanderson]

From https://github.com/mathieudutour/foam-gatsby-template/issues/9

using the latest version of the theme ([email protected]), you can add a private: true in the frontmatter of your note to make it private

This issue can probably be closed?

[astrelochnik]

I don't think this issue should be closed. The answer here suggests that to exclude certain notes from being published to our public Github Pages site we must use @mathieudutour's specific template for Foam and/or using their own gatsby-digital-garden repo and enabling a certain theme (the suggested "gatsby-theme-garden" above) within.

I think having an 'exclude', or "private: true" option ought to be included in the default Foam template at some point. Perhaps in improving #356 or #359 note templates, "public or private" options ought to auto-populate in the note's frontmatter.

All this being said @mathieudutour's digital garden repo or their Foam-specific template is absolutely amazing and is a great work-around.

[riccardoferretti]

@astrelochnik I completely agree with you. Currently there is no way in the Foam model to mark a note as being private. That means that any solution is built by a convention defined by whichever publishing solution is used on top of Foam.

The Foam model should include a property to define whether a note is public or private. Any publishing solution should use that information to include or not a note in the published site. A few thoughts:

• At minimum we need a repo wide setting, and a note specific way to mark a note as private/public
• I think this is not just about flagging a property as being private (e.g. private: true). I think something like visibility: private. This would allow for example in the future to have protected notes (only accessible after login) or maybe even role based visibility - thoughts?

---

(note: I had created a separate issue to track this task: #435 - but I actually think it's better to continue the conversation here, so the issue has been closed)

[brentjanderson]

• I think this is not just about flagging a property as being private (e.g. private: true). I think something like visibility: private. This would allow for example in the future to have protected notes (only accessible after login) or maybe even role based visibility

This is precisely how I am approaching this in the publishing tool I am building for myself. The YAML frontmatter will have a visibility property to set one or more visibility levels, with a presumed default of private or unpublished.

[riccardoferretti]

interesting, would you like to share more of your thinking/design around this? does the property have any built-in semantic? I guess private and public would, and anything else would be left to the publishing fwk to interpret? Or were you thinking something else?

[brentjanderson]

interesting, would you like to share more of your thinking/design around this? does the property have any built-in semantic? I guess private and public would, and anything else would be left to the publishing fwk to interpret? Or were you thinking something else?

Depends on how simple it should be out of the box. Permission policies can get complex in a hurry, so having a sane set of defaults that frameworks could extend would be important.

Foam Defaults

The most basic permissions I can think of:

• private: The default option, private notes are not available online at all.
• protected: Visible to any authenticated user. For static sites, this may be useless, since they don't support authorization without a backend of some kind, and I don't think it would be right for Foam to prescribe a backend to support publishing.
• public: Note is published publicly online.

The rules that I would apply:

• Any other string or array of strings would be valid, and would be interpreted by the framework involved.
• If private is in the array of strings, then all other strings should be ignored so it "fails safe". It should disallow all other permissions.
• If public is in the array of strings (and private is not), then the other permissions are ignored since public means anyone can access the note.

An array of strings makes it useful for more sophisticated frameworks where you may want to specify a set of groups that can access a note, but it would be up to the framework to interpret those groups beyond the above rules.

Examples

# This page would be restricted to these two authenticated groups and not otherwise published publicly
# It would be up to the framework to figure out if a user belonged to those groups
---
visibility:
  - employees
  - contractors
---

# Any authenticated user
---
visibility: protected
---

# Anyone, including unauthenticated users
---
visibility: public
---

A note that doesn't have any visibility set would not be available to anyone when published.

My Framework

• I'm planning on using the above semantics for my own project.
• I will have a few custom permissions for scoping some notes to specific user groups, and I plan on having account registration closed as well.

[riccardoferretti]

This is very helpful @brentjanderson.

What happens if protected is in a list of strings alongside roles? And if we want to treat protected as a role, maybe users would be a better name. But actually, the more I think about it, the more it feels like that from a Foam POV, there are 4 levels of permissions:

1. private
2. roles (any other string)
3. protected
4. public

The visibility of a note is given by the lowest level found in the visibility attribute. When conflicting levels are listed, there should be a warning.

(the above would treat public in a different way from what you proposed in your comment above)

In the end the semantic is really honored by the publishing framework, something to be aware of, so we need to be super clear about what Foam would expect.

[brentjanderson]

Your observations about conflicting fields, how to treat public, and the 4 permission levels sounds right to me. protected makes more sense to me than users unless we would consider changing public to guest or anonymous. The public/protected/private terms feel more natural to me personally, but I am happy to use whatever convention we adopt as a community.

[riccardoferretti]

yes I also prefer public, protected and private (maybe because we are developers?). Let's go with those, they are clear enough for anyone in the end IMO

[riccardoferretti]

No progress has been made here, but I think I should point out before closing the issue that this convention needs to be followed by whatever template is used to publish the Foam repo. Foam itself doesn't care/use/need this information. So the issue should be filed against individual templates.

How to make this a "standard" is a bigger question to me, but again unless we include a publishing API (which would do the filtering itself), and this is not in the roadmap atm, the convention is still only relevant at the template level.