A free (but better?) alternative to Obsidian Publish.
This repo contains an easy-to-use (read: simplistic) solution for converting an Obsidian Personal Knowledge Management System (read: bunch of random Markdowns) into a Zola site.
Credits: This repo was forked from Adidoks.
Special Thanks: Wikilink parsing is powered by obsidian-export.
v1.3.0 Satisfying Feature Requests! ✨
Bug Fixes:
- Fixed some more bugs related to unconventional filenames (e.g. containing "." and other special characters)
Improvements:
- Better local test setup (see
Local Testing
below) - Configurable root section name
- Configurable footer content
Step 1: Setup Netlify
- Turn your Obsidian vault folder into a Git repository
- Create a Netlify site pointing to that Git repository
Step 2: Edit netlify.toml
- Create
netlify.toml
in your Obsidian vault folder - Copy the content from
netlify.example.toml
in this repo and replace the appropriate settings (SITE_URL
,REPO_URL
andLANDING_PAGE
cannot be left empty).
Step 3: You're Done 🎉!
- Push your changes and get ready to become famous!
- Be Fancy: All text field settings in
netlify.toml
(e.g.LANDING_TITLE
) supports HTML syntax. And I addedAnimate.css
+Hover.css
+CSShake
for those of you who want to add a personal touch~
Step 4: Issues & Feature Requests
- If you encounter any issues, first refer to Config+FAQ. If still unsolved, just post in the
Issues
tab. It would be good to include a copy of the error log found in the Netlify panel if the issue is related to deployment. - If you have any feature request, do post an issue also. However, please this repo is intended as a one-file setup. Advanced features / detailed configurability will not be supported unless it is wanted by most users. However, I can provide help for you to implement a fork that suits your needs 🥂.
Step 5: (Optional Enhancement) Auto Sitemap Submit
To make your site more friendly to search engines, you can add a netlify plugin to automatically submit the new sitemap everytime you re-deploy the site. Just add the following to your netlify.toml
. Remember to replace baseUrl
with your SITE_URL
.
[[plugins]]
package = "netlify-plugin-submit-sitemap"
[plugins.inputs]
# The base url of your site (optional, default = main URL set in Netlify)
baseUrl = "https://peteryuen.netlify.app/"
# Path to the sitemap URL (optional, default = /sitemap.xml)
sitemapPath = "/sitemap.xml"
# Time in seconds to not submit the sitemap after successful submission
ignorePeriod = 0
# Enabled providers to submit sitemap to (optional, default = 'google', 'bing', 'yandex'). Possible providers are currently only 'google', 'bing', 'yandex'.
providers = [
"google",
"bing",
"yandex",
]
Do not copy
netlify.toml
from example site, it is unstable. Please reference fromnetlify.example.toml
.
The example site shows the capabilities of obsidian-zola
. Note that the example site uses the dev
branch of obsidian-zola
. If you see features that are available in the example site but are not available in the main branch yet, consider trying out the dev
(unstable) branch. Exact method can be referenced from the example repo's netlify.toml
.
- Install zola from the instuctions on the site
https://www.getzola.org/documentation/getting-started/installation/
- Run the following commands to install other needed dependencies
sudo apt install python-is-python3 python3-pip
andpip3 install python-slugify rtoml
(or useconda
/mamba
) - Use
git clone https://github.com/ppeetteerrs/obsidian-zola
to clone the repo to somewhere other than inside the Obsidian vault folder - Set the path to the Obsisian vault using a
.vault_path
file or the$VAULT
environment variable - use
./local-run.sh
to run the site
Disclaimer
This tool is made for people who use Obsidian as a simple and efficient note-taking app (or PKM). If you configured your Obsidian with plenty of fancy shortcodes, plugins and Obsidian-specific syntax, this tool would not (and does not intend) to support those features.
Supported
- Knowledge graph (you can also treat it as backlinks)
- LaTEX (powered by
KaTEX
, bye MathJAX fans 👋) - Partial string search (powered by
elasticlunr
) - Syntax highlighting + Fira Code!
- Customizable animations
- Navigation
- Table of content
- Typical Markdown syntax
- Strikethroughs
- Tables
- Single-line footnotes (i.e.
[^1]
in the paragraph and[^1]: xxx
later) - Checkboxes
- Link escaping pattern:
[Slides Demo](<Slides Demo>)
Unsupported
- Non-image / note embeds (e.g. videos, audio, PDF). They will be turned into links.
- Image resizing
- Highlighting text
- Comments
- Inline / Multi-line footnotes
- Mermaid Diagrams
- Do not have files with name
index.md
or_index.md
Do not have files that have the same name as its subfolder (e.g. having both(Fixed).../category1.md
and.../category1/xxx.md
is not allowed)LANDING_PAGE
needs to be set to the slugified file name ifSLUGIFY
is turned on (e.g. to useI am Home.md
,LANDING_PAGE
needs to bei-am-home
)
- (Probably will do) Backlinks / Mentioned in
- (Maybe) Lottie animations?
- (Dunno) Configurable collapse icon