├── .github └── workflows │ └── Deploy.yml ├── .gitignore ├── .vscode ├── extensions.json ├── foam.json └── settings.json ├── _layouts ├── .yarnrc ├── gatsby-browser.js ├── gatsby-config.js ├── package.json ├── src │ └── styles │ │ └── main.css └── yarn.lock ├── foam-tips.md ├── inbox.md ├── math.md ├── readme.md └── todo.md /.github/workflows/Deploy.yml: -------------------------------------------------------------------------------- 1 | name: Deploy Site 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | 8 | jobs: 9 | build: 10 | runs-on: ubuntu-20.04 11 | steps: 12 | - uses: actions/checkout@v2 13 | 14 | - name: Setup | Node 15 | uses: actions/setup-node@v2 16 | with: 17 | node-version: '14' 18 | 19 | - name: Get yarn cache directory path 20 | id: yarn-cache-dir-path 21 | run: echo "::set-output name=dir::$(yarn cache dir)" 22 | 23 | - uses: actions/cache@v2 24 | id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`) 25 | with: 26 | path: ${{ steps.yarn-cache-dir-path.outputs.dir }} 27 | key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }} 28 | restore-keys: | 29 | ${{ runner.os }}-yarn- 30 | 31 | - name: Install dependencies 32 | run: yarn 33 | working-directory: _layouts 34 | 35 | - name: Get repository name 36 | run: echo ::set-env name=REPOSITORY_NAME::$(echo "$GITHUB_REPOSITORY" | awk -F / '{print $2}') 37 | shell: bash 38 | env: 39 | ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true' 40 | 41 | - name: Build Site 42 | run: yarn build 43 | working-directory: _layouts 44 | env: 45 | PATH_PREFIX: /${{ env.REPOSITORY_NAME }} 46 | 47 | - name: Deploy 48 | uses: peaceiris/actions-gh-pages@v3 49 | with: 50 | publish_dir: ./_layouts/public 51 | github_token: ${{ secrets.GITHUB_TOKEN }} 52 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .cache/ 3 | public/ -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | // See http://go.microsoft.com/fwlink/?LinkId=827846 3 | // for the documentation about the extensions.json format 4 | "recommendations": [ 5 | // Foam's own extension 6 | "foam.foam-vscode", 7 | 8 | // Prettier for auto formatting code 9 | "esbenp.prettier-vscode", 10 | 11 | // GitLens for seeing version history inline 12 | "eamodio.gitlens", 13 | 14 | // Tons of markdown goodies (lists, tables of content, so much more) 15 | "yzhang.markdown-all-in-one", 16 | 17 | // [[wiki-links]], backlinking etc 18 | "kortina.vscode-markdown-notes", 19 | 20 | // Graph visualizer 21 | "tchayen.markdown-links", 22 | 23 | // Understated grayscale theme (light and dark variants) 24 | "philipbe.theme-gray-matter" 25 | ] 26 | } 27 | -------------------------------------------------------------------------------- /.vscode/foam.json: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/hikerpig/foam-template-gatsby-kb/652812545210dce66c27cb23bad168f09af08651/.vscode/foam.json -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "files.autoSave": "onFocusChange", 3 | "editor.minimap.enabled": false, 4 | "editor.wrappingIndent": "indent", 5 | "editor.overviewRulerBorder": false, 6 | "foam.edit.linkReferenceDefinitions": "withExtensions", 7 | "vscodeMarkdownNotes.noteCompletionConvention": "noExtension", 8 | "[markdown]": { 9 | "editor.quickSuggestions": { 10 | "other": true, 11 | "comments": false, 12 | "strings": false 13 | } 14 | }, 15 | "cSpell.language": "en-GB", 16 | "git.enableSmartCommit": true, 17 | "git.postCommitCommand": "sync", 18 | "spellright.language": [ 19 | "en" 20 | ], 21 | "spellright.documentTypes": [ 22 | "markdown", 23 | "plaintext" 24 | ], 25 | "files.exclude": { 26 | "_site/**": true 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /_layouts/.yarnrc: -------------------------------------------------------------------------------- 1 | registry https://registry.npmjs.org/ 2 | -------------------------------------------------------------------------------- /_layouts/gatsby-browser.js: -------------------------------------------------------------------------------- 1 | import 'prism-themes/themes/prism-nord.css' 2 | 3 | import 'katex/dist/katex.min.css' 4 | 5 | import './src/styles/main.css' 6 | -------------------------------------------------------------------------------- /_layouts/gatsby-config.js: -------------------------------------------------------------------------------- 1 | const path = require('path') 2 | 3 | const PATH_PREFIX = process.env.PATH_PREFIX 4 | 5 | module.exports = { 6 | // pathPrefix: PATH_PREFIX || `/foam-template-gatsby-kb`, // a. If you are using github pages, this should be the name of your repo 7 | pathPrefix: PATH_PREFIX || `/`, // b. If you are using Netlify/Vercel, your can keep it this way 8 | siteMetadata: { 9 | // some SEO configs using by gatsby-theme-kb 10 | title: `Foam`, // Replace it with your site's title 11 | author: `Your Name`, // Replace it with your name 12 | description: `My personal knowledge base`, // Replace it with your site's description 13 | }, 14 | plugins: [ 15 | { 16 | resolve: `gatsby-theme-kb`, 17 | options: { 18 | rootNote: '/readme', 19 | contentPath: `${__dirname}/..`, 20 | ignore: [ 21 | '**/_layouts/**', 22 | '**/.git/**', 23 | '**/.github/**', 24 | '**/.vscode/**', 25 | '**/.cache/**', 26 | '**/.foam/templates/**' 27 | ], 28 | // this is an option for extending `gatsby-plugin-mdx` options inside `gatsby-theme-kb`, 29 | getPluginMdx(defaultPluginMdx) { 30 | // so you can have your relative referenced files served, e.g. '../assets/img.png'. 31 | defaultPluginMdx.options.gatsbyRemarkPlugins.push({ 32 | resolve: `gatsby-remark-copy-linked-files`, 33 | options: { 34 | ignoreFileExtensions: ['md', 'mdx'], 35 | }, 36 | }) 37 | 38 | // an example of syntax highlighting 39 | defaultPluginMdx.options.gatsbyRemarkPlugins.push({ 40 | resolve: 'gatsby-remark-prismjs', 41 | options: { 42 | noInlineHighlight: true, 43 | }, 44 | }) 45 | 46 | // add math support 47 | defaultPluginMdx.options.remarkPlugins.push(require('remark-math')) 48 | if (!defaultPluginMdx.options.rehypePlugins) defaultPluginMdx.options.rehypePlugins = [] 49 | defaultPluginMdx.options.rehypePlugins.push(require('rehype-katex')) 50 | return defaultPluginMdx 51 | }, 52 | }, 53 | }, 54 | { 55 | // this plugin makes sure your static files will be served by gatsby, 56 | // but of course you need to reference them by absolute path, e.g. '/assets/img.png'. 57 | // if you have multiple directories, copy this plugin section and specify other directory 58 | // check https://github.com/csath/gatsby-plugin-copy-files-enhanced to find docs for this plugin 59 | resolve: 'gatsby-plugin-copy-files-enhanced', 60 | options: { 61 | source: path.resolve(__dirname, `../assets`), 62 | destination: '/assets', 63 | purge: false, 64 | }, 65 | }, 66 | ], 67 | } 68 | -------------------------------------------------------------------------------- /_layouts/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "foam-template-gatsby-kb", 3 | "version": "1.0.0", 4 | "description": "A foam template using gatsby-theme-kb for publishing you knowledge base", 5 | "main": "index.js", 6 | "scripts": { 7 | "dev": "gatsby develop", 8 | "build": "gatsby build --prefix-paths", 9 | "serve": "gatsby serve" 10 | }, 11 | "keywords": [ 12 | "foam" 13 | ], 14 | "author": "chenmin", 15 | "license": "MIT", 16 | "engines": { 17 | "node": "<=16.12.0" 18 | }, 19 | "dependencies": { 20 | "gatsby": "^4.6.2", 21 | "gatsby-plugin-copy-files-enhanced": "^1.1.1", 22 | "gatsby-remark-copy-linked-files": "^4.10.0", 23 | "gatsby-remark-prismjs": "^5.10.0", 24 | "gatsby-theme-kb": "^0.9.0", 25 | "prism-themes": "^1.8.0", 26 | "prismjs": "^1.24.1", 27 | "rehype-katex": "^5.0.0", 28 | "remark-math": "^3.0.1" 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /_layouts/src/styles/main.css: -------------------------------------------------------------------------------- 1 | /* ---------------- prism override ---------------------- */ 2 | pre[class*="language-"] { 3 | margin: 1em 0; 4 | } 5 | 6 | .dark-mode pre[class*="language-"] { 7 | background-color: #252931; 8 | } 9 | 10 | .light-mode pre[class*="language-"] { 11 | background-color: #2b2727; 12 | } 13 | 14 | /* ----------------end prism override ------------------- */ 15 | 16 | code { 17 | font-size: 0.9em; 18 | } 19 | -------------------------------------------------------------------------------- /foam-tips.md: -------------------------------------------------------------------------------- 1 | # Foam tips 2 | 3 | _For up-to-date tips, see [Foam Recipes](https://foambubble.github.io/foam/recipes)._ 4 | -------------------------------------------------------------------------------- /inbox.md: -------------------------------------------------------------------------------- 1 | # Inbox 2 | 3 | - Here you can write disorganised notes to be categorised later 4 | - Bullet points are useful, but it could be free form text as well 5 | - Sometimes it's better to just get things off your mind quickly, rather than stop to think where it belongs 6 | - But don't let this list get too long 7 | - Move information to more specific documents and link to them. 8 | - This helps you navigate between documents quickly 9 | - For example, you can `Cmd`+`Click` this: [[todo]] 10 | - Some notes don't end up making sense the next day 11 | - That's ok, you can just delete them! 12 | - You can always find them in your git history, if you really need it! 13 | 14 | 15 | [//begin]: # "Autogenerated link references for markdown compatibility" 16 | [todo]: todo "Todo" 17 | [//end]: # "Autogenerated link references" -------------------------------------------------------------------------------- /math.md: -------------------------------------------------------------------------------- 1 | # Math and katex 2 | 3 | With the help of `remark-math` and `rehype-katex`, math notation is supported. 4 | 5 | ## Inline math 6 | 7 | ``` 8 | Some inline math, coming right up. $T_n = a + (n-1)d$ 9 | ``` 10 | 11 | Some inline math, coming right up. $T_n = a + (n-1)d$ 12 | 13 | ## Math block 14 | 15 | Or math block: 16 | 17 | ``` 18 | $$ 19 | T_n = a + (n-1)d 20 | $$ 21 | ``` 22 | 23 | $$ 24 | T_n = a + (n-1)d 25 | $$ 26 | 27 | Special thanks to [flashshare](https://github.com/flashshare) in [#7](https://github.com/hikerpig/foam-template-gatsby-kb/issues/7). 28 | 29 | And a super helpful tutorial of [Adding math support to a Gatsby MDX blog | Nicky blogs](https://nickymeuleman.netlify.app/blog/math-gatsby-mdx#wiring-up-remark-math). 30 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Foam 2 | 3 | 👋 Welcome to your new Foam Workspace! 4 | 5 | ## Getting started 6 | 7 | This documentation assumes that you have a GitHub account and have [Visual Studio Code](https://code.visualstudio.com/) installed on your Linux/MacOS/Windows machine. 8 | 9 | 1. If you haven't yet, browse over to the main [Foam documentation workspace](https://foambubble.github.io/foam) to get an idea of what Foam is and how to use it. 10 | 2. Press "Use this template" button at [foam-template-gatsby-kb](https://github.com/hikerpig/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. 11 | 3. [Clone the repository to your local machine](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) and open it in VS Code. 12 | *Open the repository as a folder using the `File > Open...` menu item. In VS Code, "open workspace" refers to [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces).* 13 | 4. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one) 14 | 5. Open [_layouts/gatsby-config.js](_layouts/gatsby-config.js) and edit the `pathPrefix` to be the name of the repository. 15 | 16 | After setting up the repository, open [.vscode/settings.json](.vscode/settings.json) and edit, add or remove any settings you'd like for your Foam workspace. 17 | 18 | To learn more about how to use **Foam**, read the [Recipes](https://foambubble.github.io/foam/recipes) bubbles of the Foam documentation workspace. 19 | 20 | ### Some Gatsby configurations 21 | 22 | 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. 23 | 24 | Check the repo for [latest gatsby-config.js](https://github.com/hikerpig/foam-template-gatsby-kb/blob/master/_layouts/gatsby-config.js). 25 | 26 | ```js 27 | const path = require('path') 28 | 29 | const PATH_PREFIX = process.env.PATH_PREFIX 30 | 31 | module.exports = { 32 | pathPrefix: PATH_PREFIX || `/`, // b. If you are using Netlify/Vercel, your can keep it this way 33 | siteMetadata: { 34 | // some SEO configs using by gatsby-theme-kb 35 | title: `Foam`, // Replace it with your site's title 36 | author: `Your Name`, // Replace it with your name 37 | description: `My personal knowledge base`, // Replace it with your site's description 38 | }, 39 | plugins: [ 40 | { 41 | resolve: `gatsby-theme-kb`, 42 | options: { 43 | rootNote: '/readme', 44 | contentPath: `${__dirname}/..`, 45 | ignore: [ 46 | '**/_layouts/**', 47 | '**/.git/**', 48 | '**/.github/**', 49 | '**/.vscode/**', 50 | '**/.cache/**', 51 | ], 52 | // this is an option for extending `gatsby-plugin-mdx` options inside `gatsby-theme-kb`, 53 | getPluginMdx(defaultPluginMdx) { 54 | // so you can have your relative referenced files served, e.g. '../assets/img.png'. 55 | defaultPluginMdx.options.gatsbyRemarkPlugins.push({ 56 | resolve: `gatsby-remark-copy-linked-files`, 57 | options: { 58 | ignoreFileExtensions: ['md', 'mdx'], 59 | }, 60 | }) 61 | 62 | // an example of syntax highlighting 63 | defaultPluginMdx.options.gatsbyRemarkPlugins.push({ 64 | resolve: 'gatsby-remark-prismjs', 65 | options: { 66 | noInlineHighlight: true, 67 | }, 68 | }) 69 | 70 | // add math support 71 | defaultPluginMdx.options.remarkPlugins.push(require('remark-math')) 72 | if (!defaultPluginMdx.options.rehypePlugins) defaultPluginMdx.options.rehypePlugins = [] 73 | defaultPluginMdx.options.rehypePlugins.push(require('rehype-katex')) 74 | return defaultPluginMdx 75 | }, 76 | }, 77 | }, 78 | { 79 | // this plugin makes sure your static files will be served by gatsby, 80 | // but of course you need to reference them by absolute path, e.g. '/assets/img.png'. 81 | // if you have multiple directories, copy this plugin section and specify other directory 82 | // check https://github.com/csath/gatsby-plugin-copy-files-enhanced to find docs for this plugin 83 | resolve: 'gatsby-plugin-copy-files-enhanced', 84 | options: { 85 | source: path.resolve(__dirname, `../assets`), 86 | destination: '/assets', 87 | purge: false, 88 | }, 89 | }, 90 | ], 91 | } 92 | ``` 93 | 94 | ### About Syntax highlight 95 | 96 | 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. 97 | 98 | There is an example of shiki and twoslash mentioned in [this issue](https://github.com/hikerpig/foam-template-gatsby-kb/issues/5#issuecomment-782902350). 99 | 100 | ### More options 101 | 102 | For more available theme options, check [gatsby-theme-kb README](https://github.com/hikerpig/gatsby-project-kb/tree/master/packages/gatsby-theme-kb). 103 | 104 | ### Deploy 105 | 106 | #### Option 1. To Vercel 107 | 108 | Check the [demo of this repo](https://foam-template-gatsby-kb.vercel.app/) in Vercel. 109 | 110 | Goto [New Project](https://vercel.com/new) page of Vercel, import your own repo in github (after connecting your github to Vercel, of course). 111 | 112 | 1. While configuring the site, select `_layouts` as your source code directory. 113 | 114 | ![](https://i.loli.net/2021/01/28/pMxdXwuYGzF5LDg.png) 115 | 116 | 2. Select `Gatsby.js` as 'FRAMEWORK PRESET'. 117 | 118 | ![](https://i.loli.net/2021/01/28/Ccw4a9l8zeJxDXt.png) 119 | 120 | Then click the 'Deploy' button of the form, you will see Vercel building and deploying your site. 121 | 122 | #### Option 2. To Github Pages 123 | 124 | At first you need to enable GitHub Pages in your repo's settings, set `gh-pages` branch as source. 125 | 126 | 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. 127 | 128 | 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/](https://hikerpig.github.io/foam-template-gatsby-kb/). 129 | 130 | ## Using Foam 131 | 132 | We've created a few Bubbles (markdown documents) to get you started. 133 | 134 | - [[inbox]] - a place to write down quick notes to be categorised later 135 | - [[foam-tips]] - tips to get the most out of your Foam workspace 136 | - [[todo]] - a place to keep track of things to do 137 | 138 | The demo on Vercel has some of Foam docs and has more usage examples (like images), check the [feature/foam-docs branch](https://github.com/hikerpig/foam-template-gatsby-kb/tree/feature/foam-docs) to see then. 139 | 140 | ### Important configurations for foam 141 | 142 | You may need to configure Foam to work with this template, for the config `foam.edit.linkReferenceDefinitions`: 143 | 144 | - `"withoutExtensions"`, this is the default option, the generated definition url will not include the `md` extension part. 145 | - `"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. 146 | 147 | ## Note on `[[wiki-links]]` 148 | 149 | ⚠️ Until [foambubble/foam#16](https://github.com/foambubble/foam/issues/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). 150 | 151 | They should work as expected in VS Code, and in rendered GitHub Pages. 152 | 153 | 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. 154 | 155 | [//begin]: # "Autogenerated link references for markdown compatibility" 156 | [inbox]: inbox.md "Inbox" 157 | [foam-tips]: foam-tips.md "Foam tips" 158 | [todo]: todo.md "Todo" 159 | [//end]: # "Autogenerated link references" 160 | -------------------------------------------------------------------------------- /todo.md: -------------------------------------------------------------------------------- 1 | # Todo 2 | 3 | - [x] This is an example of a todo list item that's complete 4 | - [x] Todo lists are useful for keeping organised and focused 5 | - [ ] This one is not completed yet 6 | - [ ] You can mark it completed by pressing `Option`+`C` (or `Alt`+`C`) when your cursor is on this line 7 | - [ ] You can also select multiple lines and mark them all at once! 8 | - [ ] When you press enter at the end of a line, it adds a new todo item on the next line 9 | - [ ] This, and more is provided by the [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) plugin by [Yu Zhang](https://github.com/yzhang-gh) 10 | --------------------------------------------------------------------------------