ben/homefoam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

foam_sync.ps1 (LIFEBALANCE) 2025-06-26T00:38:08Z

Browse Source
This commit is contained in:
Ben Miller
2025-06-26 00:38:08 -06:00
parent 66aed86542
commit 6e31eb68ab
55 changed files with 0 additions and 2486 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/publishing/generate-gatsby-site.md
View File

@ -1,34 +0,0 @@
# Generate a site using Gatsby
## Using foam-gatsby-template
You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on GitHub or [Vercel](https://vercel.com).
### Publishing your foam to GitHub pages
It comes configured with GitHub actions to auto deploy to GitHub pages when changes are pushed to your main branch.
### Publishing your foam to Vercel
When you're ready to publish, run a local build.
```bash
cd _layouts
npm run build
```
Remove `public` from your .gitignore file then commit and push your public folder in `_layouts` to GitHub.
Log into your Vercel account. (Create one if you don't have it already.)
Import your project. Select `_layouts/public` as your root directory and click **Continue**. Then name your project and click **Deploy**.
That's it!
## Using foam-template-gatsby-kb
You can use another template [foam-template-gatsby-kb](https://github.com/hikerpig/foam-template-gatsby-kb), and host it on [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/).
## Using foam-template-gatsby-theme-primer-wiki
You can use another template [foam-template-gatsby-theme-primer-wiki](https://github.com/theowenyoung/foam-template-gatsby-theme-primer-wiki), ([Demo](https://demo-wiki.owenyoung.com/)), and host it on Github Pages, [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/).

54
docs/publishing/math-support-with-katex.md
View File

@ -1,54 +0,0 @@
# Katex Math Rendering
Apart from using the method mentioned in [[math-support-with-mathjax]], we can also use KaTeX to render our math equations in Foam. The caveat is: we can't rely on GitHub Pages to host and deploy our website anymore, because the plugin we'll be using to let Jekyll support KaTeX doesn't play well together with GitHub Pages.
The alternative solution is to using [[publish-to-vercel]] for building and publishing our website, so before you start integrating KaTeX into your Foam project, please follow the instructions to host your Foam workspace on [[publish-to-vercel]] first.
## Adding required plugins
Add the plugin `jekyll-katex` to your Foam workspace's `_config.yml` and `Gemfile` if you haven't done so already. For detailed instructions, please refer to the `#Adding a _config.yml` and `#Adding a Gemfile` in [[publish-to-vercel]].
## Loading KaTeX JS and CSS
Because we are using KaTeX to render math, we will also need to import KaTeX's JS and CSS files from CDN. The official method to load these files is documented at: [KaTeX/KaTeX#starter-template](https://github.com/KaTeX/KaTeX#starter-template). In our case, we will need to add the following code snippet to our `_layouts/page.html`:
```html
<!-- _layouts/page.html -->
---
layout: default
---
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
<!-- To automatically render math in text elements, include the auto-render extension: -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>
<!-- ... -->
```
## Adding liquid tags to wrap page content
The plugin `jekyll-katex` focuses on rendering:
- Single math equations wrapped inside `katex` liquid tags like {% raw %}`{% katex %} ... {% endkatex %}`{% endraw %}.
- Or multiple math equations in paragraphs wrapped inside {% raw %}`{% katexmm %} ... {% endkatexmm %}`{% endraw %}.
In our case, we'll be using the latter tag to wrap our {% raw %}`{{ content }}`{% endraw %}. Wrap {% raw %}`{{ content }}`{% endraw %} in the liquid tags inside `_layouts/page.html` like so:
```html
<!-- _layouts/page.html -->
<!-- ... -->
{% raw %}{% katexmm %} {{ content }} {% endkatexmm %}{% endraw %}
<!-- ... -->
```
## Render equations in Foam's homepage as well
You may have noticed that we only made modifications to the template `_layouts/page.html`, which means that `_layouts/home.html` won't have KaTeX support. If you wan't to render math in Foam's home page, you'll need to make the same modifications to `_layouts/home.html` as well.
Finally, if all goes well, then our site hosted on Vercel will support rendering math equations with KaTeX after committing these changes to GitHub. Here's a demo of the default template with KaTeX support: [Foam Template with KaTeX support](https://foam-template.vercel.app/).

51
docs/publishing/math-support-with-mathjax.md
View File

@ -1,51 +0,0 @@
---
layout: mathjax
---
# Math Support
Published Foam pages don't support math formulas by default. To enable this feature, you can add the following code snippet to the end of `_layouts/page.html`:
```html
<script src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
inlineMath: [['$','$']]
}
});
</script>
```
This approach uses the [MathJax](https://www.mathjax.org/) library to render anything delimited by ```$``` (customizable in the snippet above) pairs to inline math and ```$$``` to blocks of math (like a html div tag) using with the AMS-LaTeX dialect embedded within MathJax.
Example of inline math using `$...$`:
`$e^{i \pi}+1=0$`, becomes $e^{i \pi}+1=0$
Example of a math block using `$$...$$`:
`$$ f_{\mathbf{X}}\left(x_{1}, \ldots, x_{k}\right)=\frac{\exp \left(-\frac{1}{2}(\mathbf{x}-\boldsymbol{\mu})^{\mathrm{T}} \mathbf{\Sigma}^{-1}(\mathbf{x}-\boldsymbol{\mu})\right)}{\sqrt{(2 \pi)^{k}|\mathbf{\Sigma}|}} $$`
Becomes:
$$ f_{\mathbf{X}}\left(x_{1}, \ldots, x_{k}\right)=\frac{\exp \left(-\frac{1}{2}(\mathbf{x}-\boldsymbol{\mu})^{\mathrm{T}} \mathbf{\Sigma}^{-1}(\mathbf{x}-\boldsymbol{\mu})\right)}{\sqrt{(2 \pi)^{k}|\mathbf{\Sigma}|}} $$
## Alternative approaches
There are other dialects of LaTeX (instead of AMS), and other JavaScript rendering libraries you may want to use. In a future version of Foam, we may support KaTeX syntax out of the box, but at this time, these integrations are left as an exercise to the user.
## Why don't my Math expressions work on my Foam's home page?
If you want the index page of your Foam site to render maths, you'll need to add that to `_layouts/home.html` as well, or change the layout of the index page to be "page" instead of "home" by putting this Front Matter on the top of your `readme.md/index.md`:
```
---
layout: page
---
# Your normal title here
```
Reference: [How to support latex in github-pages](https://stackoverflow.com/questions/26275645/how-to-support-latex-in-github-pages)

49
docs/publishing/publish-to-github-pages.md
View File

@ -1,49 +0,0 @@
# GitHub Pages
1. In VSCode workspace settings set `"foam.edit.linkReferenceDefinitions": "withoutExtensions"`
2. Execute the “Foam: Run Janitor” command from the command palette.
3. [Turn **GitHub Pages** on in your repository settings](https://guides.github.com/features/pages/).
- The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
- GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
## How to publish locally
If you want to test your published foam, follow the instructions:
- <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll>
- <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll>
Assuming you have installed ruby/jekyll and the rest:
- `touch Gemfile`
- open the file and paste the following:
```
source 'https://rubygems.org'
gem "github-pages", "VERSION"
```
replacing `VERSION` with the latest from <https://rubygems.org/gems/github-pages> (e.g. `gem "github-pages", "209"`)
- `bundle`
- `bundle exec jekyll 3.9.0 new .`
- edit the `Gemfile` according to the instructions at [Creating Your Site](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll#creating-your-site) Point n.8
- `bundle exec jekyll serve`
## Other templates
There are many other templates which also support publish your foam workspace to github pages
* gatsby-digital-garden
* [repo](https://github.com/mathieudutour/gatsby-digital-garden)
* [demo-website](https://mathieudutour.github.io/gatsby-digital-garden/)
* foam-mkdocs-template
* [repo](https://github.com/Jackiexiao/foam-mkdocs-template)
* [demo-website](https://jackiexiao.github.io/foam/)
* foam-jekyll-template
* [repo](https://github.com/hikerpig/foam-jekyll-template)
* [demo-website](https://hikerpig.github.io/foam-jekyll-template/)
[[todo]] [[good-first-task]] Improve this documentation

16
docs/publishing/publish-to-github.md
View File

@ -1,16 +0,0 @@
# Publish to GitHub
The standard [foam-template](https://github.com/foambubble/foam-template) is ready to be published to GitHub, and GitHub pages.
## Enable navigation in GitHub
To allow navigation from within the GitHub repo, make sure to generate the link references, by setting
- `Foam › Edit: Link Reference Definitions` -> `withExtensions`
See [[link-reference-definitions]] for more information.
## Customising the style
You can edit `assets/css/style.scss` to change how published pages look.

224
docs/publishing/publish-to-gitlab-pages.md
View File

@ -1,224 +0,0 @@
# GitLab Pages
You don't have to use GitHub to serve Foam pages. You can also use GitLab.
Gitlab pages can be kept private for private repo, so that your notes are still private.
## Setup a project
### Generate the directory from GitHub
Generate a solution using the [Foam template](https://github.com/foambubble/foam-template).
Change the remote to GitLab, or copy all the files into a new GitLab repo
## Publishing pages with Gatsby
### Setup the Gatsby config
Add a .gatsby-config.js file where:
* `$REPO_NAME` correspond to the name of your gtlab repo.
* `$USER_NAME` correspond to your gitlab username.
```js
const path = require("path");
const pathPrefix = `/$REPO_NAME`;
// Change me
const siteMetadata = {
title: "A title",
shortName: "A short name",
description: "",
imageUrl: "/graph-visualization.jpg",
siteUrl: "https://$USER_NAME.gitlab.io",
};
module.exports = {
siteMetadata,
pathPrefix,
flags: {
DEV_SSR: true,
},
plugins: [
`gatsby-plugin-sharp`,
{
resolve: "gatsby-theme-primer-wiki",
options: {
defaultColorMode: "night",
icon: "./path_to/logo.png",
sidebarComponents: ["tag", "category"],
nav: [
{
title: "Github",
url: "https://github.com/$USER_NAME/",
},
{
title: "Gitlab",
url: "https://gitlab.com/$USER_NAME/",
},
],
editUrl:
"https://gitlab.com/$USER_NAME/$REPO_NAME/tree/main/",
},
},
{
resolve: "gatsby-source-filesystem",
options: {
name: "content",
path: `${__dirname}`,
ignore: [`**/\.*/**/*`],
},
},
{
resolve: "gatsby-plugin-manifest",
options: {
name: siteMetadata.title,
short_name: siteMetadata.shortName,
start_url: pathPrefix,
background_color: `#f7f0eb`,
display: `standalone`,
icon: path.resolve(__dirname, "./path_to/logo.png"),
},
},
{
resolve: `gatsby-plugin-sitemap`,
},
{
resolve: "gatsby-plugin-robots-txt",
options: {
host: siteMetadata.siteUrl,
sitemap: `${siteMetadata.siteUrl}/sitemap/sitemap-index.xml`,
policy: [{ userAgent: "*", allow: "/" }],
},
},
],
};
```
And a `package.json` file containing:
```json
{
"private": true,
"name": "wiki",
"version": "1.0.0",
"license": "MIT",
"scripts": {
"develop": "gatsby develop -H 0.0.0.0",
"start": "gatsby develop -H 0.0.0.0",
"build": "gatsby build",
"clean": "gatsby clean",
"serve": "gatsby serve",
"test": "echo test"
},
"dependencies": {
"@primer/react": "^34.1.0",
"@primer/css": "^17.5.0",
"foam-cli": "^0.11.0",
"gatsby": "^3.12.0",
"gatsby-plugin-manifest": "^3.12.0",
"gatsby-plugin-robots-txt": "^1.6.9",
"gatsby-plugin-sitemap": "^5.4.0",
"gatsby-source-filesystem": "^3.12.0",
"gatsby-theme-primer-wiki": "^1.14.5",
"react": "^17.0.2",
"react-dom": "^17.0.2"
}
}
```
The theme will be based on [gatsby-theme-primer-wiki](https://github.com/theowenyoung/gatsby-theme-primer-wiki).
To test the theme locally first run `yarn install` and then use `gatsby develop` to serve the website.
See gatsby documentation for more details.
### Set-up the CI for deployment
Create a `.gitlab-ci.yml` file containing:
```yml
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Pages/Gatsby.gitlab-ci.yml
image: node:latest
stages:
- deploy
pages:
stage: deploy
# This folder is cached between builds
# https://docs.gitlab.com/ee/ci/yaml/index.html#cache
cache:
paths:
- node_modules/
# Enables git-lab CI caching. Both .cache and public must be cached, otherwise builds will fail.
- .cache/
- public/
script:
- yarn install
- ./node_modules/.bin/gatsby build --prefix-paths
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
This pipeline will now serve your website on every push to the main branch of your project.
## Publish with Jekyll
### Add a _config.yaml
Add another file to the root directory (the one with `readme.md` in it) called `_config.yaml` (no extension)
```yaml
title: My Awesome Foam Project
baseurl: "" # the subpath of your site, e.g. /blog
url: "/" # the base hostname & protocol for your site
theme: jekyll-theme-minimal
plugins:
- jekyll-optional-front-matter
optional_front_matter:
remove_originals: true
defaults:
-
scope:
path: "" # we need to add this to properly render layouts
values:
layout: "default"
```
You can choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/)
### Add a Gemlock file
Add another file to the root directory (the one with `readme.md` in it) called `Gemfile` (no extension)
```ruby
source "https://rubygems.org"
gem "jekyll"
gem "jekyll-theme-minimal"
gem "jekyll-optional-front-matter"
```
Commit the file and push it to gitlab.
### Setup CI/CD
1. From the project home in GitLab click `Set up CI/CD`
2. Choose `Jekyll` as your template from the template dropdown
3. Click `commit`
4. Now when you go to CI / CD > Pipelines, you should see the code running
### Troubleshooting
- *Could not locate Gemfile* - You didn't follow the steps above to [Add a Gemlock file](#add-a-gemlock-file)
- *Conversion error: Jekyll::Converters::Scss encountered an error while converting* You need to reference a theme.
- *Pages are running in CI/CD, but I only ever see `test`, and never deploy* - Perhaps you've renamed the main branch (from master) - check the settings in `.gitlab-ci.yml` and ensure the deploy command is running to the branch you expect it to.
- *I deployed, but my .msd files don't seem to be being converted into .html files* - You need a gem that GitHub installs by default - check `gem "jekyll-optional-front-matter"` appears in the `Gemfile`

18
docs/publishing/publish-to-netlify-with-eleventy.md
View File

@ -1,18 +0,0 @@
# Publish to Netlify with Eleventy
You can use [foam-eleventy-template](https://github.com/juanfrank77/foam-eleventy-template) to generate a static site with [Eleventy](https://www.11ty.dev/), and host it online on [Netlify](https://www.netlify.com/).
With this template you can
- Have control over what to publish and what to keep private
- Customize the styling of the site to your own liking
## Publishing your foam
When you're ready to publish, import the GitHub repository you created with **foam-eleventy-template** into your Netlify account. (Create one if you don't have it already.)
Once that's done, all you have to do is make changes to your workspace in VS Code and push them to the main branch on GitHub. Netlify will recognize the changes, deploy them automatically and give you a link where your Foam is published.
That's it!
You can now see it online and use that link to share it with your friends, so that they can see it too.

83
docs/publishing/publish-to-vercel.md
View File

@ -1,83 +0,0 @@
# Publish to Vercel
This #recipe shows you how to deploy the default Foam website template to Vercel.
[Vercel](https://vercel.com/) is a static website hosting solution similar to GitHub Pages (see [[publish-to-github-pages]]).
## Setting up the project
### Using Foam's template
Generate a GitHub repository using the default [Foam template](https://github.com/foambubble/foam-template), this will be the workspace that we will be deploying with Vercel. This workspace is a barebone Jekyll source website, which means we can customize and install plugins just like any other Jekyll websites.
As we won't be using GitHub Pages, we will be adding a few configuration files in order to help Vercel pick up on how to build our site.
### Adding a `_config.yml`
First, we'll need to add a `_config.yml` at the root directory. This is the Jekyll configuration file. In here, we will set the site's title, theme, repository and permalink options, and also tell Jekyll what plugins to use:
```yaml
# _config.yml
title: Foam
# All the plugins we will be installing now that we won't be using GitHub Pages
plugins:
- jekyll-katex # optional
- jekyll-default-layout
- jekyll-relative-links
- jekyll-readme-index
- jekyll-titles-from-headings
- jekyll-optional-front-matter
# The default Jekyll theme we will be using
theme: jekyll-theme-primer
# The GitHub repository that we are hosting our foam workspace from
repository: user/repo
# Generate permalinks in format specified in: https://jekyllrb.com/docs/permalinks/#built-in-formats
permalink: pretty
```
The `theme` specifies a theme for our deployed Jekyll website. The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates. We can also choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/).
The `plugins` specifies a list of Jekyll plugins that we will be installing in the next section. As we won't be using GitHub Pages, we'll need to install these plugins that GitHub Pages installs for us under the hood.
_If you want to use LaTeX rendered with KaTeX (which is what the plugin `jekyll-katex` does), you can specify it here. And yes, one of the benefits of deploying with Vercel is that we can use KaTeX to render LaTeX! More on: [[math-support-with-katex]]_
### Adding a `Gemfile`
Next up, we'll create another new file called `Gemfile` in the root directory. This is where we will let Vercel know what plugins to install when building our website.
In our `Gemfile`, we need to specify our Ruby packages:
```ruby
# Gemfile
source "https://rubygems.org"
gem "jekyll"
gem "kramdown-parser-gfm"
gem "jekyll-theme-primer"
gem "jekyll-optional-front-matter"
gem "jekyll-default-layout"
gem "jekyll-relative-links"
gem "jekyll-readme-index"
gem "jekyll-titles-from-headings"
gem "jekyll-katex" # Optional, the package that enables KaTeX math rendering
```
### Enable math rendering with KaTeX (optional)
Besides adding the plugin `jekyll-katex` in `_config.yml` and `Gemfile`, we'll also have to follow the guides in [[math-support-with-katex]] to let our site fully support using KaTeX to render math equations.
### Committing changes to GitHub repo
Finally, commit the newly created files to GitHub.
## Importing project to Vercel
First, import our foam workspace (GitHub repository) to Vercel with [Vercel's _Import Git Repository_](https://vercel.com/import/git). Paste our GitHub repo's url and Vercel will automatically pull and analyze the tool we use to deploy our website. (In our case: Jekyll.)
Next, select the folder to deploy from if prompted. If we are using the default template, then Vercel will default to the root directory of our Foam workspace.
Finally, if all is successful, Vercel will show the detected framework: Jekyll. Press `Deploy` to proceed on publishing our project.
![](../../assets/images/vercel-detect-preset.png)
And now, Vercel will take care of building and rendering our foam workspace each time on push. Vercel will publish our site to `xxx.vercel.app`, we can also define a custom domain name for our Vercel website.

24
docs/publishing/publishing.md
View File

@ -1,24 +0,0 @@
# Publishing pages
Foam pages can be published.
TODO add publishing TOC
## Foam site generator?
Another case of the [[build-vs-assemble]] dilemma. We could provide a better publishing experience by building a bespoke static site generator (or a gatsby plugin) that's aware of Foam conventions (backlinks etc.)
Eventually we should probably do it, as that would unlock a huge amount of power, but we should always strive to keep it optional.
At a bare minimum, Foam repos should remain valid markdown, and should be publishable by any sufficiently complete markdown to html generation tools.
Would be cool if Foam pages could be published. Some ideas here.
- [x] Easymode: Make your GitHub public
- [x] Static site generator integration, publish from GH actions to GitHub pages / Netlify etc!!!
- [ ] Add annotations to pages for setting visibility (many ways to do this)
- [ ] Public by default, and `@private` annotations
- [ ] Private by default, and `@public` annotations
- [ ] Only public `/public` folder, just move a document there, no annotation needed
- [ ] More granular access control? Email someone a link with a hash? [Testing](testing.md)