Sadly I can not maintain Oboe anymore. For a great alternative, have a look at srid/neuron for you static file generation. If anyone would like to fork Oboe and maintain it themselves, send me an email at km@aasrud and I will make sure people are redirected.
Installation - Usage - Tips
Oboe is a Python command line tool made to convert an Obsidian vault into a vault of HTML files, with the goal of publishing them as static files. It depends on the excellent markdown2 by trentm for Markdown parsing, but also deals with parsing Obsidian's flavor of Markdown. In addition, Oboe handles the structure of your vault and supports templates.
- Make sure Python and PIP are installed.
- Install Oboe with
pip install git+https://github.com/kmaasrud/oboe
Supply the path to an Obsidian vault, and Oboe will convert all its notes into HTML, appended by the notes' backlinks.
oboe <path to vault>
These HTML-files are by default placed in the directory ./html
. To specify another output directory, use the flag -o
or --output-directory
.
oboe <path to vault> -o <output directory>
By default, Oboe only converts notes in the vault root, and not those inside sub-directories. To include sub-directories, add them with the flag -d
or --sub-directories
. For example, say you have the folders Daily notes
and Zettels
that you want to have converted. In this case, run
oboe <path to vault> -d "Daily notes" "Zettels"
If you want to include all sub-directories recursively and add every note in your vault regardless of where it is located, add the -d
flag without any arguments.
The output is not very exciting from the get-go. It needs some style and structure. This is done by using a HTML template. A template must have the formatters {title}
and {content}
present. Their value should be obvious. The template file is supplied to obsidian-html
by the flag -t
or --template
, like this:
oboe <path to vault> -t template.html
Here you can add metadata, link to CSS-files and add unified headers/footers to all the pages. Here's an example of how I use the template function on my own hosted vault.
Note that because of the way Python does formatting, the template cannot contain single curly braces other than the abovementioned formatters. To include Javascript or CSS in your template, always use double curly braces (e.g. {{
). These will be changed into single braces in the final result.
Oboe supports only converting notes that contain a certain tag. The filter is specified via the -f
or --filter
flag. For example, say you had a tag #physics
for notes relating to physics, and the same for #chemistry
. To convert all notes relating to physics and/or chemistry, run Oboe like this:
oboe <path to vault> -f physics chemistry
Filters are not strict, so Oboe will convert any notes containing any of the tags in the filter. Filters can also be negated by prefixing a tag with .
, for example:
oboe <path to vault> -f physics .chemistry
The above would convert all notes with the #physics
tag, but exclude all notes with the #chemistry
tag. If the filter contains only exclusions, Oboe will convert every note except those who match the exclusion.
-
-e
or--add-file-extensions
: Most web-servers do not need the.html
file extension in URLs to find the correct file. However, that might be needed when browsing the converted vault locally. If you experience issues with this or want all links to have a.html
extension, just add this flag when running. -
-b
or--omit-backlink-dash
: Removes the-
in front of the backlink when inserted in html.
Make a GitHub Actions workflow using the YAML below, and your vault will be published to GitHub Pages every time you push to the repository.
-
Make sure you have GitHub Pages set up in the vault, and that it has
gh-pages
/root
as its source. -
Copy and modify the following YAML job to match your repository. Add it to your vault repository as
.github/workflows/publish.yml
.name: Publish to GitHub Pages on: push: branches: [ master ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python 3.8 uses: actions/setup-python@v2 with: python-version: 3.8 - name: Install oboe run: | python -m pip install --upgrade pip pip install git+https://github.com/kmaasrud/oboe.git - name: Generate HTML through oboe run: oboe ./vault -o ./out -t ./template.html -d daily - name: Publish uses: s0/git-publish-subdir-action@develop env: REPO: self BRANCH: gh-pages FOLDER: out GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
????
-
PROFIT!!!
By loading KaTeX in the HTML template and initializing it with $
and $$
as delimiters, you will have TeX support on the exported documents.
Just add this to the bottom of you template's body:
<!-- KaTeX -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"
integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz"
crossorigin="anonymous"></script>
<!-- To automatically render math in text elements, include the auto-render extension: -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"
integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI"
crossorigin="anonymous"></script>
<!-- Parsing single dollar signs -->
<script>
document.addEventListener("DOMContentLoaded", function () {{
renderMathInElement(document.body, {{
delimiters: [
{{left: "$$", right: "$$", display: true}},
{{left: "\\[", right: "\\]", display: true}},
{{left: "$", right: "$", display: false}},
{{left: "\\(", right: "\\)", display: false}}
]
}});
}});
</script>
Note the double
{
's. This is to work around how Python formatting works, and will be correct in the outputted HTML.
Using highlight.js, syntax highlighting is easily achieved.
Just add this to the bottom of you template's body:
<!-- Syntax highlighting through highlight.js -->
<link rel="stylesheet" href="https://unpkg.com/@highlightjs/[email protected]/styles/default.min.css">
<script src="https://unpkg.com/@highlightjs/[email protected]/highlight.min.js"></script>
<script>
// Ignore highlighting of mermaid
hljs.configure({{noHighlightRe: /^mermaid$/}});
hljs.initHighlightingOnLoad();
</script>
Note the double
{
's. This is to work around how Python formatting works, and will be correct in the outputted HTML.