hikerpig / foam-template-gatsby-kb

A Foam/Obsidian template using gatsby-theme-kb for publishing your knowledge base

Foam

👋 Welcome to your new Foam Workspace!

Getting started

This documentation assumes that you have a GitHub account and have Visual Studio Code installed on your Linux/MacOS/Windows machine.

1. If you haven't yet, browse over to the main Foam documentation workspace to get an idea of what Foam is and how to use it.
2. Press "Use this template" button at foam-template-gatsby-kb (that's this repository!) to fork it to your own GitHub account. If you want to keep your thoughts to yourself, remember to set the repository private.
3. Clone the repository to your local machine and open it in VS Code. Open the repository as a folder using the File > Open... menu item. In VS Code, "open workspace" refers to multi-root workspaces.
4. When prompted to install recommended extensions, click Install all (or Show Recommendations if you want to review and install them one by one)
5. Open _layouts/gatsby-config.js and edit the pathPrefix to be the name of the repository.

After setting up the repository, open .vscode/settings.json and edit, add or remove any settings you'd like for your Foam workspace.

To learn more about how to use Foam, read the Recipes bubbles of the Foam documentation workspace.

Some Gatsby configurations

Check the _layouts/gatsby-config.js file, and there is some configs you should concern if you want to deploy your site and view it correctly.

Check the repo for latest gatsby-config.js.

const path = require('path')

const PATH_PREFIX = process.env.PATH_PREFIX

module.exports = {
  pathPrefix: PATH_PREFIX || `/`, // b. If you are using Netlify/Vercel, your can keep it this way
  siteMetadata: {
    // some SEO configs using by gatsby-theme-kb
    title: `Foam`, // Replace it with your site's title
    author: `Your Name`, // Replace it with your name
    description: `My personal knowledge base`, // Replace it with your site's description
  },
  plugins: [
    {
      resolve: `gatsby-theme-kb`,
      options: {
        rootNote: '/readme',
        contentPath: `${__dirname}/..`,
        ignore: [
          '**/_layouts/**',
          '**/.git/**',
          '**/.github/**',
          '**/.vscode/**',
          '**/.cache/**',
        ],
        // this is an option for extending `gatsby-plugin-mdx` options inside `gatsby-theme-kb`,
        getPluginMdx(defaultPluginMdx) {
          // so you can have your relative referenced files served, e.g. '../assets/img.png'.
          defaultPluginMdx.options.gatsbyRemarkPlugins.push({
            resolve: `gatsby-remark-copy-linked-files`,
            options: {
              ignoreFileExtensions: ['md', 'mdx'],
            },
          })

          // an example of syntax highlighting
          defaultPluginMdx.options.gatsbyRemarkPlugins.push({
            resolve: 'gatsby-remark-prismjs',
            options: {
              noInlineHighlight: true,
            },
          })

          // add math support
          defaultPluginMdx.options.remarkPlugins.push(require('remark-math'))
          if (!defaultPluginMdx.options.rehypePlugins) defaultPluginMdx.options.rehypePlugins = []
          defaultPluginMdx.options.rehypePlugins.push(require('rehype-katex'))
          return defaultPluginMdx
        },
      },
    },
    {
      // this plugin makes sure your static files will be served by gatsby,
      //   but of course you need to reference them by absolute path, e.g. '/assets/img.png'.
      // if you have multiple directories, copy this plugin section and specify other directory
      // check https://github.com/csath/gatsby-plugin-copy-files-enhanced to find docs for this plugin
      resolve: 'gatsby-plugin-copy-files-enhanced',
      options: {
        source: path.resolve(__dirname, `../assets`),
        destination: '/assets',
        purge: false,
      },
    },
  ],
}

About Syntax highlight

The default gatsby config has a simple support of codeblock syntax highlight through gatsby-remark-prismjs and some css file. If you have other preference, feel free to remove those configs and add your own.

There is an example of shiki and twoslash mentioned in this issue.

More options

For more available theme options, check gatsby-theme-kb README.

Deploy

Option 1. To Vercel

Check the demo of this repo in Vercel.

Goto New Project page of Vercel, import your own repo in github (after connecting your github to Vercel, of course).

1. While configuring the site, select _layouts as your source code directory.

2. Select Gatsby.js as 'FRAMEWORK PRESET'.

Then click the 'Deploy' button of the form, you will see Vercel building and deploying your site.

Option 2. To Github Pages

At first you need to enable GitHub Pages in your repo's settings, set gh-pages branch as source.

And once you push the master branch, github actions will build the site and add generated files to gh-pages branch. The action workflow config is located in .github/workflows/Deploy.yml. It comes with you when you fork this repository, if you don't need it or want to get rid the gh-pages noise, just delete the file.

After the building is done, you can visit your site in https://{yourname}.github.io/{your-repo-name}/, e.g. https://hikerpig.github.io/foam-template-gatsby-kb/.

Using Foam

We've created a few Bubbles (markdown documents) to get you started.

• [inbox] - a place to write down quick notes to be categorised later
• [foam-tips] - tips to get the most out of your Foam workspace
• [todo] - a place to keep track of things to do

The demo on Vercel has some of Foam docs and has more usage examples (like images), check the feature/foam-docs branch to see then.

Important configurations for foam

You may need to configure Foam to work with this template, for the config foam.edit.linkReferenceDefinitions:

• "withoutExtensions", this is the default option, the generated definition url will not include the md extension part.
• "off", with this option selected, Foam won't generate link definitions in the bottom of the document, this might be inconvenient for you to navigate across your files on Github, but totally fine with gatsby-theme-kb.

Note on [[wiki-links]]

⚠️ Until foambubble/foam#16 is resolved, [[wiki-links]] links (like the links above) won't work in the GitHub Markdown preview (i.e. this Readme on github.com).

They should work as expected in VS Code, and in rendered GitHub Pages.

If GitHub preview (or general 100% support with all Markdown tools) is a requirement, for the time being you can use the standard [description](page.md) syntax.

foam-template-gatsby-kb's Issues

Feature Request: deploy to github pages

There is something wrong with gatsby-theme-kb due to the '/foam-template-gatsby-kb' prefix.
Need some effort to sort it out.

Documents other than notes displaying on the table of contents?

Hi!

I wonder if there would be any way to display documents linked (like pdfs) on the left hand side table of contents and not just the md files.

I don't know if this is doable, but it would be great! 😄

(mmm... I now realise mongodb-cheatsheet is not displaying there either... 🤔 . Need to check that)

How to add gatsby-remark-katex?

I'd like to render math equations with katex and I wonder where I should put the gatsby-remark-katex plugin? Thanks!

fails to render relative wikilinks

I have a directory structure that looks something like this

• dir1
  • sub_dir1
    • notes.md
  • intro.md
• dir2
  ... and so on

intro.md has a wiki link to notes.md. Foam creates a relative backlink on the markdown page

[//begin]: # "Autogenerated link references for markdown compatibility"
[notes]: <sub_dir1/notes.md> "Notes"
[//end]: # "Autogenerated link references"

This works fine in vscode but the generated pages fails to understand the relative backlinks.

Include mermaid diagrams

Add mermaid rendering.

When a user adds a mermaid block like

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

The diagram should be rendered automatically.

Where to put CNAME in Gastby structure?

Quick answer: point 4 below

Thanks for this theme, it works lovely even for people like myself who don't know Gatsby at all.

I had issues that my custom domain was deleted upon every commit. I had to search and play around a little, but here's the solution in case anybody runs into the same issue (which is probably perfectly logical to people who know Gatsby):

1. When you create your custom domain, Github actually saves that as a textfile called "CNAME" in the root of your page, which in our case is the root of the "gh-pages" branch of your repository.
2. This file is deleted every time the page is rebuilt, so upon every commit.
3. You can place such static components in a folder called "static" in any Gatsby project. In our case, though, the folder structure is a little different.
4. The correct location is to place your textfile CNAME in your master branch where the markdown files are, in the folder _layouts/static/CNAME (you'll have to create "static" and the CNAME file, containing ONLY your domain name, e.g. in my case marc.chehab.ch)

Just in case this helps anybody else. (Quite verbose description to make sure even people who don't know / care about Gatsby follow.)

Thanks again for this wonderful theme and kind regards from Zurich!

Marc

Issues with links with alternative title when deploying to GitHub pages

Hello!

I'm using this theme to render some notes, and I noticed a weird behaviour when I deployed the page using GitHub pages.

When using wikilinks with an alternative name, like this:

text that references [[pagetitle|a name]]

The page link is correctly handled in Visual Studio, but there are some issues on the deployed website:

1. the alternative name is ignored, and the link text is the whole wikilink text;
2. the linked page always refers the root folder, even if the link refers to a subfolder;
3. the graph does not show the correct references.

If I don't use the alternative name, everything works well.

Here's a real example:

Under the /azure folder I have several documents. In particular, I have azure-storage-redundancy-types.md, azure-virtual-machines.md, and azure-availability-zones.md.

Wrong link generation

The first page references the other two like this:

ZRS replicates your Azure Storage data **synchronously** across **three [[azure-availability-zones|availability zones]] in the primary region**.

and

When creating a storage account, you must select the primary region. The paired secondary region is assigned automatically, based on [[azure-region-pairs]], and cannot be changed.

The VSCode extension generates the following links:

[//begin]: # "Autogenerated link references for markdown compatibility"
[azure-availability-zones|availability zones]: azure-availability-zones "Azure Availability Zones"
[azure-region-pairs]: azure-region-pairs "Azure Region Pairs"
[//end]: # "Autogenerated link references"

Notice that the title of the "Availability zone" link is wrong: it should be "availability zones", not "Azure Availability Zones".

The markdown preview on VSCode is correct:

while the link on the deployed site uses the wrong title:

Wrong link destination

Clicking on the link, you get redirected to a page on the root folder (that does not exist) instead of the correct one under /azure.

Graph

By looking at the graph generated on VSCode, we can see 1 inbound link and 2 outbound links:

While on the deployed site, we have only 1 outbound link:

Code blocks and syntax highlight

I'm not sure this happens only with your template, but the first line of code blocks gets a ½ character indentation, so for this snippet, for example:

```sql
ALTER ROLE <username> SET client_encoding TO 'utf8';
ALTER ROLE <username> SET default_transaction_isolation TO 'read committed';
ALTER ROLE <username> SET timezone TO 'UTC';
``` (need to write this so the code doesn't render in the issue and shows what I use in the md file, please disregard)

I get this result:

You can see that the first line gets a ½ character indentation. Strange!

Also, I don't get any syntax coloring for my code snippets, regardless of the language I pick.

Is it possible to render wiki links without the double bracket?

As per the current demo page:

Is it possible to remove the brackets when rendering the web page? :)

Links reload page since changes from 02/21

I don't know what changed in the latest version from February 13th but now all the wikilinks result in a reload.

Additionally, all backlinks are broken and they show multiple times.

I updated package.json and gatsby-config to the latest version, by the way.

I'm not sure how to sort this.

Package.json update needed

Hi, first thank you for making this awesome template!

I've been trying to setup the blog, but I've been getting build error.

error /vercel/path0/_layouts/node_modules/lmdb-store: Command failed.

The first thing I've tried was removing the yarn.lock file, and it seemed to work.

But my site started breaking down.

1. Dark mode isn't working

2. It seems like db has some sort of issue. Cannot see the category.
   

My solution was specifying the node version in package.json like this. It seems like the project is only compatible with node version 16.12.0.

{
  "name": "foam-template-gatsby-kb",
  "version": "1.0.0",
  "description": "A foam template using gatsby-theme-kb for publishing you knowledge base",
  "engines": {
    "node": "<=16.12.0"
  },

It would be nice to have update in the README file or update in package.json file.

Show tags for every page

We can assign tags for every bubble.

It would be useful to see those tags on the GitHub rendered page.

re-organizing folders

Hi, any idea how I can re-organize folders or pin notes, as now it is alphabetically by default?
https://devconwiki.vercel.app/
https://github.com/elgirafo/devconwiki