mirror of
https://github.com/foambubble/foam-template.git
synced 2025-07-24 19:08:55 +00:00
Compare commits
2 commits
8f1696ef13
...
0afcc9a2dd
| Author | SHA1 | Date | |
|---|---|---|---|
|
0afcc9a2dd | ||
|
71c0e8a477 |
12 changed files with 311 additions and 81 deletions
10
.vscode/keybindings.json
vendored
10
.vscode/keybindings.json
vendored
|
|
@ -1,11 +1,5 @@
|
|||
// This file is not automatically applied.
|
||||
// To enable it, follow these steps:
|
||||
|
||||
// 1. Open the Command Palette: `cmd + shift + p`
|
||||
// 2. Start typing "keyboard shortcuts"
|
||||
// 3. Select "Preferences: Open Keyboard Shortcuts (JSON)"
|
||||
// 4. Paste the snippet below or add it to the existing shortcuts array:
|
||||
|
||||
// This file does not get automatically applied
|
||||
// @TODO: Make it work or document how to copy to user keybindings
|
||||
[
|
||||
{
|
||||
"key": "cmd+shift+n",
|
||||
|
|
|
|||
BIN
assets/images/pdf_output.png
Normal file
BIN
assets/images/pdf_output.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
|
|
@ -1,8 +1,8 @@
|
|||
# Daily Notes
|
||||
|
||||
Daily notes allow you to quickly create and access a new notes file for each day. This is a surpisingly effective and increasingly common strategy to organize notes and manage events.
|
||||
Daily notes allow you to quickly create and access a new notes file for each day. This is a surprisingly effective and increasingly common strategy to organize notes and manage events.
|
||||
|
||||
View today's note file by running the `Foam: Open Daily Note` command, by using the shortcut `alt+d` (note: shortcuts can be [overridden](https://code.visualstudio.com/docs/getstarted/keybindings)), or by using [#snippets](#Snippets). The name, location, and title of daily notes files is [#configurable](#Configuration).
|
||||
View today's note file by running the `Foam: Open Daily Note` command, by using the shortcut `alt+d` (note: shortcuts can be [overridden](https://code.visualstudio.com/docs/getstarted/keybindings)), or by using [#snippets](#Snippets). The name, location, and title of daily notes files are [#configurable](#Configuration).
|
||||
|
||||
## Roam-style Automatic Daily Notes
|
||||
|
||||
|
|
@ -29,11 +29,11 @@ Create a link to a recent daily note using [snippets](https://code.visualstudio.
|
|||
|
||||
## Configuration
|
||||
|
||||
By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the workspace's `journals` folder, with a heading `yyyy-mm-dd`.
|
||||
By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the workspace's `journals` folder, with the heading `yyyy-mm-dd`.
|
||||
|
||||
These settings can be overridden in your workspace or global `.vscode/settings.json` file, using the [**dateformat** date masking syntax](https://github.com/felixge/node-dateformat#mask-options):
|
||||
|
||||
It's possible to customize path and heading of your daily notes, by following the [dateformat masking syntax](https://github.com/felixge/node-dateformat#mask-options).
|
||||
It's possible to customize the path and heading of your daily notes, by following the [dateformat masking syntax](https://github.com/felixge/node-dateformat#mask-options).
|
||||
The following properties can be used:
|
||||
|
||||
```json
|
||||
|
|
@ -45,7 +45,7 @@ The following properties can be used:
|
|||
|
||||
The above configuration would create a file `journal/daily-note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
|
||||
|
||||
> NOTE: It is possible to set the filepath of a daily note according to the date using the special [[note-properties]] configurable for [[Note Templates]]. Specifically see [[note-templates#Example of date-based|Example of date-based filepath]]. Using the template property will override any setting configured through `.vscode/settings.json`.
|
||||
> NOTE: It is possible to set the filepath of a daily note according to the date using the special [[note-properties]] configurable for [[Note Templates]]. Specifically, see [[note-templates#Example of date-based|Example of date-based filepath]]. Using the template property will override any setting configured through `.vscode/settings.json`.
|
||||
|
||||
## Extend Functionality (Weekly, Monthly, Quarterly Notes)
|
||||
|
||||
|
|
|
|||
|
|
@ -38,6 +38,7 @@ A sample configuration object is provided below, you can provide as many or as l
|
|||
"foam.graph.style": {
|
||||
"background": "#202020",
|
||||
"fontSize": 12,
|
||||
"fontFamily": "Sans-Serif",
|
||||
"lineColor": "#277da1",
|
||||
"lineWidth": 0.2,
|
||||
"particleWidth": 1.0,
|
||||
|
|
@ -50,6 +51,7 @@ A sample configuration object is provided below, you can provide as many or as l
|
|||
|
||||
- `background` background color of the graph, adjust to increase contrast
|
||||
- `fontSize` size of the title font for each node
|
||||
- `fontFamily` font of the title font for each node
|
||||
- `lineColor` color of the edges between nodes in the graph
|
||||
- `lineWidth` thickness of the edges between nodes
|
||||
- `particleWidth` size of the particle animation showing link direction when highlighting a node
|
||||
|
|
|
|||
|
|
@ -1,22 +1,22 @@
|
|||
# Link Reference Definitions
|
||||
|
||||
When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension can automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is not needed to navigate your workspace with foam-vscode, but is useful for files to remain compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wikilinks]]`.
|
||||
When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/main/packages/foam-vscode) extension can automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is not needed to navigate your workspace with foam-vscode, but is useful for files to remain compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wikilinks]]`.
|
||||
|
||||
## Example
|
||||
|
||||
The following example:
|
||||
|
||||
```md
|
||||
- [[wikilinks]]
|
||||
- [[github-pages]]
|
||||
```
|
||||
```md
|
||||
- [[wikilinks]]
|
||||
- [[github-pages]]
|
||||
```
|
||||
|
||||
...generates the following link reference definitions to the bottom of the file:
|
||||
|
||||
```md
|
||||
[wikilinks]: wikilinks "Wikilinks"
|
||||
[github-pages]: github-pages "GitHub Pages"
|
||||
```
|
||||
```md
|
||||
[wikilinks]: wikilinks 'Wikilinks'
|
||||
[github-pages]: github-pages 'GitHub Pages'
|
||||
```
|
||||
|
||||
You can open the [raw markdown](https://foambubble.github.io/foam/features/link-reference-definitions.md) to see them at the bottom of this file
|
||||
You can open the [raw markdown](https://foambubble.github.io/foam/user/features/link-reference-definitions.md) to see them at the bottom of this file
|
||||
|
|
@ -53,15 +53,15 @@ There are three options for excluding files from your Foam project:
|
|||
|
||||
1. `files.exclude` (from VSCode) will prevent the folder from showing in the file explorer.
|
||||
|
||||
> "Configure glob patterns for excluding files and folders. For example, the file explorer decides which files and folders to show or hide based on this setting. Refer to the Search: Exclude setting to define search-specific excludes."
|
||||
> "Configure glob patterns for excluding files and folders. For example, the file explorer decides which files and folders to show or hide based on this setting. Refer to the Search: Exclude setting to define search-specific excludes."
|
||||
|
||||
2. `files.watcherExclude` (from VSCode) prevents VSCode from constantly monitoring files for changes.
|
||||
|
||||
> "Configure paths or glob patterns to exclude from file watching. Paths or basic glob patterns that are relative (for example `build/output` or `*.js`) will be resolved to an absolute path using the currently opened workspace. Complex glob patterns must match on absolute paths (i.e. prefix with `**/` or the full path and suffix with `/**` to match files within a path) to match properly (for example `**/build/output/**` or `/Users/name/workspaces/project/build/output/**`). When you experience the file watcher process consuming a lot of CPU, make sure to exclude large folders that are of less interest (such as build output folders)."
|
||||
> "Configure paths or glob patterns to exclude from file watching. Paths or basic glob patterns that are relative (for example `build/output` or `*.js`) will be resolved to an absolute path using the currently opened workspace. Complex glob patterns must match on absolute paths (i.e. prefix with `**/` or the full path and suffix with `/**` to match files within a path) to match properly (for example `**/build/output/**` or `/Users/name/workspaces/project/build/output/**`). When you experience the file watcher process consuming a lot of CPU, make sure to exclude large folders that are of less interest (such as build output folders)."
|
||||
|
||||
3. `foam.files.ignore` (from Foam) ignores files from being added to the Foam graph.
|
||||
|
||||
> "Specifies the list of globs that will be ignored by Foam (e.g. they will not be considered when creating the graph). To ignore the all the content of a given folder, use `<folderName>/**/*`" (requires reloading VSCode to take effect).
|
||||
> "Specifies the list of globs that will be ignored by Foam (e.g. they will not be considered when creating the graph). To ignore the all the content of a given folder, use `<folderName>/**/*`" (requires reloading VSCode to take effect).
|
||||
|
||||
For instance, if you're using a local instance of [Jekyll](https://jekyllrb.com/), you may find that it writes copies of each `.md` file into a `_site` directory, which may lead to Foam generating references to them instead of the original source notes.
|
||||
|
||||
|
|
|
|||
|
|
@ -32,6 +32,7 @@ Some properties have special meaning for Foam:
|
|||
| `title` | will assign the name to the note that you will see in the graph, regardless of the filename or the first heading (also see how to [[write-notes-in-foam]]) |
|
||||
| `type` | can be used to style notes differently in the graph (also see [[graph-visualization]]). The default type for a document is `note` unless otherwise specified with this property. |
|
||||
| `tags` | can be used to add tags to a note (see [[tags]]) |
|
||||
| `alias` | can be used to add aliases to the note. an alias will show up in the link autocompletion |
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -40,7 +41,7 @@ For example:
|
|||
title: "Note Title"
|
||||
type: "daily-note"
|
||||
tags: daily, funny, planning
|
||||
|
||||
alias: alias1, alias2
|
||||
---
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ Note templates are `.md` files located in the special `.foam/templates` director
|
|||
|
||||
Create a template:
|
||||
|
||||
* Run the `Foam: Create New Template` command from the command palette
|
||||
* OR manually create a regular `.md` file in the `.foam/templates` directory
|
||||
- Run the `Foam: Create New Template` command from the command palette
|
||||
- OR manually create a regular `.md` file in the `.foam/templates` directory
|
||||
|
||||
|
||||
|
||||
|
|
@ -17,8 +17,8 @@ _Theme: Ayu Light_
|
|||
|
||||
To create a note from a template:
|
||||
|
||||
* Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new template if none exist.
|
||||
* OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md`, if it exists)
|
||||
- Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new template if none exist.
|
||||
- OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md`, if it exists)
|
||||
|
||||
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ _Theme: Ayu Light_
|
|||
### Default template
|
||||
|
||||
The `.foam/templates/new-note.md` template is special in that it is the template that will be used by the `Foam: Create New Note` command.
|
||||
Customize this template to contain content that you want included every time you create a note. To begin it is *recommended* to define the YAML Front-Matter of the template similar to the following:
|
||||
Customize this template to contain content that you want included every time you create a note. To begin it is _recommended_ to define the YAML Front-Matter of the template similar to the following:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
|
@ -40,7 +40,7 @@ type: basic-note
|
|||
### Default daily note template
|
||||
|
||||
The `.foam/templates/daily-note.md` template is special in that it is the template that will be used when creating daily notes (e.g. by using `Foam: Open Daily Note`).
|
||||
Customize this template to contain content that you want included every time you create a daily note. To begin it is *recommended* to define the YAML Front-Matter of the template similar to the following:
|
||||
Customize this template to contain content that you want included every time you create a daily note. To begin it is _recommended_ to define the YAML Front-Matter of the template similar to the following:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
|
@ -54,12 +54,12 @@ Templates can use all the variables available in [VS Code Snippets](https://code
|
|||
|
||||
In addition, you can also use variables provided by Foam:
|
||||
|
||||
| Name | Description |
|
||||
| -------------------- | ------------ |
|
||||
| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new |
|
||||
| `FOAM_TITLE` | The title of the note. If used, Foam will prompt you to enter a title for the note. |
|
||||
| `FOAM_TITLE_SAFE` | The title of the note in a file system safe format. If used, Foam will prompt you to enter a title for the note unless `FOAM_TITLE` has already caused the prompt. |
|
||||
| `FOAM_SLUG` | The sluggified title of the note (using the default github slug method). If used, Foam will prompt you to enter a title for the note unless `FOAM_TITLE` has already caused the prompt. |
|
||||
| Name | Description |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new |
|
||||
| `FOAM_TITLE` | The title of the note. If used, Foam will prompt you to enter a title for the note. |
|
||||
| `FOAM_TITLE_SAFE` | The title of the note in a file system safe format. If used, Foam will prompt you to enter a title for the note unless `FOAM_TITLE` has already caused the prompt. |
|
||||
| `FOAM_SLUG` | The sluggified title of the note (using the default github slug method). If used, Foam will prompt you to enter a title for the note unless `FOAM_TITLE` has already caused the prompt. |
|
||||
| `FOAM_DATE_*` | `FOAM_DATE_YEAR`, `FOAM_DATE_MONTH`, `FOAM_DATE_WEEK` etc. Foam-specific versions of [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables). Prefer these versions over VS Code's. |
|
||||
|
||||
### `FOAM_DATE_*` variables
|
||||
|
|
@ -70,7 +70,7 @@ For example, `FOAM_DATE_YEAR` has the same behaviour as VS Code's `CURRENT_YEAR`
|
|||
|
||||
By default, prefer using the `FOAM_DATE_` versions. The datetime used to compute the values will be the same for both `FOAM_DATE_` and VS Code's variables, with the exception of the creation notes using the daily note template.
|
||||
|
||||
For more nitty-gritty details about the supported date formats, [see here](https://github.com/foambubble/foam/blob/master/packages/foam-vscode/src/services/variable-resolver.ts).
|
||||
For more nitty-gritty details about the supported date formats, [see here](https://github.com/foambubble/foam/blob/main/packages/foam-vscode/src/services/variable-resolver.ts).
|
||||
|
||||
#### Relative daily notes
|
||||
|
||||
|
|
@ -84,8 +84,8 @@ For example, given this daily note template (`.foam/templates/daily-note.md`):
|
|||
|
||||
## Here's what I'm going to do today
|
||||
|
||||
* Thing 1
|
||||
* Thing 2
|
||||
- Thing 1
|
||||
- Thing 2
|
||||
```
|
||||
|
||||
When the `/tomorrow` snippet is used, `FOAM_DATE_` variables will be populated with tomorrow's date, as expected.
|
||||
|
|
@ -97,11 +97,11 @@ When creating notes in any other scenario, the `FOAM_DATE_` values are computed
|
|||
|
||||
Templates can also contain metadata about the templates themselves. The metadata is defined in YAML "Frontmatter" blocks within the templates.
|
||||
|
||||
| Name | Description |
|
||||
| ------------- | ---------------------- |
|
||||
| Name | Description |
|
||||
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `filepath` | The filepath to use when creating the new note. If the filepath is a relative filepath, it is relative to the current workspace. |
|
||||
| `name` | A human readable name to show in the template picker. |
|
||||
| `description` | A human readable description to show in the template picker. |
|
||||
| `name` | A human readable name to show in the template picker. |
|
||||
| `description` | A human readable description to show in the template picker. |
|
||||
|
||||
Foam-specific variables (e.g. `$FOAM_TITLE`) can be used within template metadata. However, VS Code snippet variables are ([currently](https://github.com/foambubble/foam/pull/655)) not supported.
|
||||
|
||||
|
|
@ -146,9 +146,10 @@ It is possible to vary the `filepath` value based on the current date using the
|
|||
---
|
||||
type: daily-note
|
||||
foam_template:
|
||||
description: Daily Note for $FOAM_TITLE
|
||||
filepath: "C:\\Users\\foam_user\\foam_notes\\journal\\$FOAM_DATE_YEAR\\$FOAM_DATE_MONTH-$FOAM_DATE_MONTH_NAME_SHORT\\$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE-daily-note.md"
|
||||
description: Daily Note for $FOAM_TITLE
|
||||
filepath: "C:\\Users\\foam_user\\foam_notes\\journal\\$FOAM_DATE_YEAR\\$FOAM_DATE_MONTH-$FOAM_DATE_MONTH_NAME_SHORT\\$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE-daily-note.md"
|
||||
---
|
||||
|
||||
# $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE Daily Notes
|
||||
```
|
||||
|
||||
|
|
@ -166,7 +167,7 @@ If your template already has a YAML Frontmatter block, you can add the Foam temp
|
|||
|
||||
#### Limitations
|
||||
|
||||
Foam only supports adding the template metadata to *YAML* Frontmatter blocks. If the existing Frontmatter block uses some other format (e.g. JSON), you will have to add the template metadata to its own YAML Frontmatter block.
|
||||
Foam only supports adding the template metadata to _YAML_ Frontmatter blocks. If the existing Frontmatter block uses some other format (e.g. JSON), you will have to add the template metadata to its own YAML Frontmatter block.
|
||||
|
||||
Further, the template metadata must be provided as a [YAML block mapping](https://yaml.org/spec/1.2/spec.html#id2798057), with the attributes placed on the lines immediately following the `foam_template` line:
|
||||
|
||||
|
|
@ -210,7 +211,7 @@ foam_template:
|
|||
---
|
||||
|
||||
---
|
||||
existing_frontmatter: "Existing Frontmatter block"
|
||||
existing_frontmatter: 'Existing Frontmatter block'
|
||||
---
|
||||
This is the rest of the template
|
||||
```
|
||||
|
|
|
|||
|
|
@ -36,31 +36,31 @@ _Note that first entry in `.order` file defines wiki's home page._
|
|||
|
||||
While you are pushing changes to GitHub, you won't see the wiki updated if you don't add Azure as a remote. You can push to multiple repositories simultaneously.
|
||||
|
||||
1. First open a terminal and check if Azure is added running: `git remote show origin`. If you don't see Azure add it in the output then follow these steps.
|
||||
2. Rename your current remote (most likely named origin) to a different name by running: `git remote rename origin main`
|
||||
3. You can then add the remote for your second remote repository, in this case, Azure. e.g `git remote add azure https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes`. You can get it from: Repos->Files->Clone and copy the URL.
|
||||
4. Now, you need to set up your origin remote to push to both of these. So run: `git config -e` and edit it.
|
||||
5. Add the `remote origin` section to the bottom of the file with the URLs from each remote repository you'd like to push to. You'll see something like that:
|
||||
1. First open a terminal and check if Azure is added running: `git remote show origin`. If you don't see Azure add it in the output then follow these steps.
|
||||
2. Rename your current remote (most likely named origin) to a different name by running: `git remote rename origin main`
|
||||
3. You can then add the remote for your second remote repository, in this case, Azure. e.g `git remote add azure https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes`. You can get it from: Repos->Files->Clone and copy the URL.
|
||||
4. Now, you need to set up your origin remote to push to both of these. So run: `git config -e` and edit it.
|
||||
5. Add the `remote origin` section to the bottom of the file with the URLs from each remote repository you'd like to push to. You'll see something like that:
|
||||
|
||||
```bash
|
||||
[core]
|
||||
```bash
|
||||
[core]
|
||||
...
|
||||
(ignore this part)
|
||||
...
|
||||
(ignore this part)
|
||||
...
|
||||
[branch "master"]
|
||||
remote = github
|
||||
merge = refs/heads/master
|
||||
[branch "main"]
|
||||
remote = github
|
||||
merge = refs/heads/main
|
||||
[remote "github"]
|
||||
url = git@github.com:username/repo.git
|
||||
fetch = +refs/heads/*:refs/remotes/github/*
|
||||
url = git@github.com:username/repo.git
|
||||
fetch = +refs/heads/*:refs/remotes/github/*
|
||||
[remote "azure"]
|
||||
url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
|
||||
fetch = +refs/heads/*:refs/remotes/azure/*
|
||||
url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
|
||||
fetch = +refs/heads/*:refs/remotes/azure/*
|
||||
[remote "origin"]
|
||||
url = git@github.com:username/repo.git
|
||||
url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
|
||||
```
|
||||
url = git@github.com:username/repo.git
|
||||
url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
|
||||
```
|
||||
|
||||
6. You can then push to both repositories by: `git push origin master` or a single one using: `git push github master` or `git push azure master`
|
||||
6. You can then push to both repositories by: `git push origin main` or a single one using: `git push github main` or `git push azure main`
|
||||
|
||||
For more information, read the [Azure DevOps documentation](https://docs.microsoft.com/en-us/azure/devops/project/wiki/publish-repo-to-wiki).
|
||||
|
|
|
|||
|
|
@ -29,6 +29,9 @@ on:
|
|||
jobs:
|
||||
store_data:
|
||||
runs-on: ubuntu-latest
|
||||
# If you encounter a 403 error from a workflow run, try uncommenting the following 2 lines (taken from: https://stackoverflow.com/questions/75880266/cant-make-push-on-a-repo-with-github-actions accepted answer)
|
||||
# permissions:
|
||||
# contents: write
|
||||
steps:
|
||||
- uses: actions/checkout@master
|
||||
- uses: anglinb/foam-capture-action@main
|
||||
|
|
|
|||
53
docs/recipes/export-to-pdf.md
Normal file
53
docs/recipes/export-to-pdf.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
# Export to PDF
|
||||
|
||||
This #recipe shows how to export a note to PDF.
|
||||
|
||||
## Required extensions
|
||||
|
||||
- **[vscode-pandoc](https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vscode-pandoc)**
|
||||
|
||||
## Required third-party tools
|
||||
|
||||
- [Pandoc](https://pandoc.org/installing.html)
|
||||
- A [LaTeX distribution](https://www.latex-project.org/get/) such as TeXLive (Linux), MacTeX (MacOS), or MikTeX (Windows)
|
||||
|
||||
Check that Pandoc is installed by opening a terminal and running `pandoc --version`.
|
||||
|
||||
Check that Pandoc can produce PDFs with LaTeX by running the following in the terminal.
|
||||
|
||||
```
|
||||
echo It is working > test.md
|
||||
pandoc test.md -o test.pdf
|
||||
```
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Create a folder in your workspace named `.pandoc`. Take note of the full path to this directory. The rest of this recipe will refer to this path as `$WORKSPACE/.pandoc`.
|
||||
|
||||
2. Download the template file [`foam.latex`](https://raw.githubusercontent.com/Hegghammer/foam-templates/main/foam.latex) from [Hegghammer/foam-templates](https://github.com/Hegghammer/foam-templates) and place it in `$WORKSPACE/.pandoc`.
|
||||
|
||||
3. In VSCode, open `settings.json` for your user (or just for your workspace if you prefer), and add the following line:
|
||||
|
||||
```
|
||||
"pandoc.pdfOptString": "--from=markdown+wikilinks_title_after_pipe --resource-path $WORKSPACE/.pandoc --template foam --listings",
|
||||
```
|
||||
|
||||
Make sure to replace `$WORKSPACE/.pandoc` with the real full path to the `.pandoc` directory you created earlier.
|
||||
|
||||
4. Open a Foam note in VSCode.
|
||||
|
||||
5. Press `Ctrl` + `k`, `p`. Choose "pdf", and press `Enter`.
|
||||
|
||||
The PDF should look something like this:
|
||||
|
||||
|
||||
|
||||
## Options
|
||||
|
||||
If you include a name in the `author` parameter in the YAML of the Foam note, that name will feature in the PDF header on the top left.
|
||||
|
||||
If you don't want syntax highlighting and frames around the codeblocks, remove `--listings` from the `pandoc.pdfOptString` parameter in `settings.json`.
|
||||
|
||||
## Further customization
|
||||
|
||||
If you know some LaTeX, you can [tweak](https://bookdown.org/yihui/rmarkdown-cookbook/latex-template.html) the `foam.latex` template to your needs. Alternatively, you can supply another ready-made template such as [Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template); just place the `TEMPLATE_NAME.latex` file in `$WORKSPACE/.pandoc`. You can also use all of Pandoc's [other functionalities](https://learnbyexample.github.io/customizing-pandoc/) by tweaking the `pandoc.pdfOptString` parameter in `settings.json`.
|
||||
173
docs/recipes/generate-material-for-mkdocs-site.md
Normal file
173
docs/recipes/generate-material-for-mkdocs-site.md
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
# Generate a site using the Material for MkDocs theme
|
||||
|
||||
Configuring a static-site generator (SSG) to publish your Foam provides access to functionality not available through Foam's default publishing mechanism. For example, compare the [original Foam documentation site](https://foambubble.github.io/foam/) with a [Material for MkDocs version](https://djplaner.github.io/foam-with-material-for-mkdocs/) created using the simple configuration detailed below. Try out the search functionality on the Material for MkDocs version. This [digital garden](https://djon.es/memex) and this [blog](https://djon.es/blog/) provide more advanced examples of Foam content published using Material for MkDocs.
|
||||
|
||||
The following explains how to configure the [Material for MkDocs theme](https://squidfunk.github.io/mkdocs-material/) for the [MkDocs SSG](https://www.mkdocs.org) to publish your Foam.
|
||||
|
||||
Like most SSGs (e.g. [Gatsby](https://www.gatsbyjs.com/) is another SSG that can be [used to publish your Foam](https://foambubble.github.io/foam/user/publishing/generate-gatsby-site)) site content is accepted in the form of Markdown files. Like those produced by Foam. SSGs differ in the languages they are written in (MkDocs is Python, Gatsby is Javascript and React) and the features they provide. MkDocs and Material for MkDocs are designed to support project documentation. Gatsby is more general purpose and provides a nice feature set.
|
||||
|
||||
You choose your poison.
|
||||
|
||||
## Requirements
|
||||
|
||||
To use Material for MkDocs to publish your Foam you need:
|
||||
|
||||
- An existing Foam workspace with content.
|
||||
- [Python installed on your computer](https://realpython.com/installing-python/).
|
||||
- Some familiarity and comfort with using the command line on your computer.
|
||||
|
||||
## Instructions
|
||||
|
||||
Configuring Material for MkDocs to publish your Foam involves the following steps:
|
||||
|
||||
1. [Install Material for MkDocs and other requirements](#install-material-for-mkdocs-and-other-requirements).
|
||||
|
||||
Install the Material for MkDocs theme, MkDocs, and other required Python modules.
|
||||
|
||||
2. [Configure Material for MkDocs for your Foam](#configure-material-for-mkdocs-for-your-foam).
|
||||
|
||||
Create a `mkdocs.yml` file in the root of your Foam workspace directory. This file configures Material for MkDocs to work with your Foam.
|
||||
|
||||
2. [Preview and test your site locally](#preview-and-test-your-site-locally).
|
||||
|
||||
Run MkDocs to preview and test your Material for MkDocs Foam site locally. Good for testing and local use.
|
||||
|
||||
3. [Further customise Material for MkDocs](#further-customise-material-for-mkdocs).
|
||||
|
||||
Explore and leverage the additional configuration settings, possible customisations, and additional themes and plugins to customise your site to your needs.
|
||||
|
||||
4. [Publish your site](#publish-your-site).
|
||||
|
||||
Publish your Material for MkDocs Foam site to the web for others to enjoy. There are many options for publishing your site, including GitHub, GitLab, Netlify, and others.
|
||||
|
||||
### Install Material for MkDocs and other requirements
|
||||
|
||||
Material for MkDocs provides [detailed installation instructions](https://squidfunk.github.io/mkdocs-material/getting-started/) which cover the full range of options for installing and configuring Material for MkDocs. The following is a summary of the recommended process.
|
||||
|
||||
1. Within your Foam workspace directory, create a [Python virtual environment](https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment)
|
||||
|
||||
- `python -m venv .venv`
|
||||
- `source .venv/bin/activate` (Linux/Mac) or `.venv\Scripts\activate` (Windows)
|
||||
|
||||
2. Install Material for MkDocs
|
||||
|
||||
- `pip install mkdocs-material`
|
||||
|
||||
3. Install additional Python modules
|
||||
|
||||
- `pip install mkdocs-roamlinks-plugin`
|
||||
- `pip install mkdocs-exclude`
|
||||
|
||||
### Configure Material for MkDocs for your Foam
|
||||
|
||||
To configure Material for MkDocs for your Foam workspace, create a `mkdocs.yml` file in the root of your Foam workspace directory. Below you will find a sample `mkdocs.yml` file (adapted from the [foam-mkdocs-template repository](https://github.com/Jackiexiao/foam-mkdocs-template/tree/master)). Copy and paste it into your `mkdocs.yml` file, then edit it to suit your needs. In particular, don't forget to change the `site_name` and `site_url` to match your Foam workspace. Though this can be left a little later.
|
||||
|
||||
Material for MkDocs provides documentation on both [minimal](https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration) and [advanced](https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration) configuration of `mkdocs.yml`. Which are revisited in the [customise section below](#further-customise-your-site)
|
||||
|
||||
```yaml
|
||||
site_name: My site # Change this to your site name
|
||||
site_url: https://mydomain.org/mysite # change this
|
||||
theme:
|
||||
name: material
|
||||
features:
|
||||
- navigation.expand
|
||||
- tabs
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
- pymdownx.tabbed
|
||||
- nl2br
|
||||
- toc:
|
||||
permalink: '#'
|
||||
slugify: !!python/name:pymdownx.slugs.uslugify
|
||||
- admonition
|
||||
- codehilite:
|
||||
guess_lang: false
|
||||
linenums: false
|
||||
- footnotes
|
||||
- meta
|
||||
- def_list
|
||||
- pymdownx.arithmatex
|
||||
- pymdownx.betterem:
|
||||
smart_enable: all
|
||||
- pymdownx.caret
|
||||
- pymdownx.critic
|
||||
- pymdownx.details
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.magiclink
|
||||
- pymdownx.mark
|
||||
- pymdownx.smartsymbols
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tasklist
|
||||
- pymdownx.tilde
|
||||
plugins:
|
||||
- search
|
||||
- roamlinks
|
||||
- exclude:
|
||||
glob:
|
||||
- "*.tmp"
|
||||
- "*.pdf"
|
||||
- "*.gz"
|
||||
regex:
|
||||
- '.*\.(tmp|bin|tar)$'
|
||||
```
|
||||
|
||||
### Preview and test your site locally
|
||||
|
||||
MkDocs provides a live preview server allowing you to preview and test your Material for MkDocs Foam site. The server will continue to rebuid your site as you write.
|
||||
|
||||
The simplest method to use the preview service is to run the following command whilst in the rood directory of your Foam workspace:
|
||||
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
See the Material for MkDocs site for more, including [how to run the preview server via docker](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write)
|
||||
|
||||
### Further customise your site
|
||||
|
||||
Further customisation is available through expanding the configuration of Material for MkDocs, using additional MkDocs plugins, customising HTML/CSS, using Markdown extensions, writing your own Python scripts, and more.
|
||||
|
||||
For more on the available customisation paths, see the following:
|
||||
|
||||
- Material for MkDocs [Advanced configuration](https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration) or the [Set up section](https://squidfunk.github.io/mkdocs-material/setup/)
|
||||
|
||||
For more configuration options to be included in your `mkdocs.yml` file, including customising: colours, fonts, language, icons, navigation, header, footer etc.
|
||||
|
||||
- Material for MkDocs [Customisation](https://squidfunk.github.io/mkdocs-material/customization/)
|
||||
|
||||
For advice on enhancing the visual design of your site by customising and replacing provided HTML, CSS, and Javascript.
|
||||
|
||||
- Material for MkDocs [Reference](https://squidfunk.github.io/mkdocs-material/reference/)
|
||||
|
||||
An overview of customisation methods that can be used directly within your Markdown files, including: admonitions, annotations, buttons, code blocks, content tabs, data tables, diagrams, grids, Mathematics, etc.
|
||||
|
||||
- a [catalog of 300 MkDocs projects and plugins](https://github.com/mkdocs/catalog#readme)
|
||||
|
||||
For functionality and ideas not included in Material for MkDocs, including: additional themes, plugins, and extensions.
|
||||
|
||||
### Building and publishing your site
|
||||
|
||||
As a Static Site Generator (SSG), MkDocs generates a collection of static HTML and other types of files. Publishing your site involves building those HTML files and placing them onto your web server. The method will vary depending on your web server and hosting provider.
|
||||
|
||||
The MkDocs documentation site provides an explanation of the [simplest method to publish your site to any provider](https://www.mkdocs.org/user-guide/deploying-your-docs/#other-providers) using `mkdocs build` and `scp`.
|
||||
|
||||
The Material for MkDocs [publish page](https://squidfunk.github.io/mkdocs-material/publishing-your-site/) lists options for publishing to
|
||||
|
||||
- GitHub using [mkdocs](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-mkdocs)
|
||||
|
||||
Perhaps the simplest method, if you are already using GitHub to host your Foam workspace.
|
||||
|
||||
- GitHub using [GitHub actions](https://squidfunk.github.io/mkdocs-material/publishing-your-site/github-actions/)
|
||||
|
||||
A more automated method of publishing your site to GitHub, using GitHub actions.
|
||||
|
||||
- [GitLab](https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-mkdocs)
|
||||
|
||||
- [Cloudflage pages](https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-cloudflare/)
|
||||
|
||||
- [Netlify](https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-netlify/)
|
||||
|
||||
- [Fly.io](https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/#prerequisites)
|
||||
|
||||
- [Scaleway](https://www.scaleway.com/en/docs/tutorials/using-bucket-website-with-mkdocs/)
|
||||
|
||||
|
|
@ -1,19 +1,21 @@
|
|||
<!-- omit in toc -->
|
||||
|
||||
# Recipes
|
||||
|
||||
A #recipe is a guide, tip or strategy for getting the most out of your Foam workspace!
|
||||
|
||||
- [Contribute](#contribute)
|
||||
- [Take smart notes](#take-smart-notes)
|
||||
- [Discover](#discover)
|
||||
- [Organise](#organise)
|
||||
- [Write](#write)
|
||||
- [Version control](#version-control)
|
||||
- [Publish](#publish)
|
||||
- [Collaborate](#collaborate)
|
||||
- [Workflow](#workflow)
|
||||
- [Creative ideas](#creative-ideas)
|
||||
- [Other](#other)
|
||||
- [Recipes](#recipes)
|
||||
- [Contribute](#contribute)
|
||||
- [Take smart notes](#take-smart-notes)
|
||||
- [Discover](#discover)
|
||||
- [Organise](#organise)
|
||||
- [Write](#write)
|
||||
- [Version control](#version-control)
|
||||
- [Publish](#publish)
|
||||
- [Collaborate](#collaborate)
|
||||
- [Workflow](#workflow)
|
||||
- [Creative ideas](#creative-ideas)
|
||||
- [Other](#other)
|
||||
|
||||
## Contribute
|
||||
|
||||
|
|
@ -75,11 +77,12 @@ A #recipe is a guide, tip or strategy for getting the most out of your Foam work
|
|||
- Publish using community templates
|
||||
- [[publish-to-netlify-with-eleventy]] by [@juanfrank77](https://github.com/juanfrank77)
|
||||
- [[generate-gatsby-site]] by [@mathieudutour](https://github.com/mathieudutour) and [@hikerpig](https://github.com/hikerpig)
|
||||
|
||||
- [[generate-material-for-mkdocs-site]] by [@djplaner](https://github.com/djplaner)
|
||||
- Make the site your own by [[publish-to-github]].
|
||||
- Render math symbols, by either
|
||||
- adding client-side [[math-support-with-mathjax]] to the default [[publish-to-github-pages]] site
|
||||
- adding a custom Jekyll plugin to support [[math-support-with-katex]]
|
||||
- Export note to PDF [[export-to-pdf]]
|
||||
|
||||
## Collaborate
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue