jobindjohn / obsidian-publish-mkdocs

A Template to Publish Obsidian/Foam Notes on Github Pages (uses MkDocs)

Publish your Obsidian Notes

MkDocs template

Would you like to take some of your notes in Obsidian and make it public?

This template gives you an easy (and automated) way to publish your Obsidian notes (or blog!) on your Github pages.

With this template, you get these out-of-the-box:

• an awesome website based on Material theme, complete with a search bar (Checkout this template repo published here)
• get the Obsidian/Roam style [[wikilinks]] from your vault in your published notes
• Toggle between light and dark mode
• Blog folder

Quick start

1. Create a new github repository using this template. Click the green button at the top or use this link.

2. Give a name to your repository. By default your notes will be published at <https://username.github.io/repo-name/>
   • Copy only the main branch while creating the repo from the template
3. Clone the repository you generated into your Obsidian folder/vault.
4. Move your notes that you would like to make public to the repo-name/docs folder.
   • Easiest way to do this would be using drag and drop within Obsidian
5. Commit and push the changes. Github actions will take care of the rest, publishing your notes using MkDocs, with the Material theme.
6. Go to Settings > Pages and select the select the Source as your gh-pages branch.

Not working for you? Open an issue and let me know what went wrong.

Configuring your website

How do I arrange notes as sections and pages?

By default, the sections and pages will follow the folder structure within /docs. The folders and sub-folders will show up as sections. Try not to have white spaces in your folder and file names, as these will be converted to HTML links. The webpage heading will be the same as the first-level heading in the markdown note.

• If you would like to arrange the pages manually, then use the nav option in the mkdocs.yml configuration file at the root of this repo to set custom page navigation.
  • For example, see the setup for the Blue Book at github. Managing each page using nav can become cumbersome as the number of notes increase though!
• The Materials theme provides multiple options to arrange sections, use navigation tabs, and many other helpful navigation setups

Alternatives

• datopian/obsidian-flowershow: plugin for publishing with flowershow direct from your obsidian vault.
• kmaasrud/oboe: tool to convert an Obsidian vault into a static directory of HTML files.
• Jackiexiao/foam-mkdocs-template: template for Obsidian/Foam using mkdocs/mkdocs-material/mkdocs-roamlinks-plugin
• foambubble/foam-template: Foam workpace template
• ObsidianPublisher/obsidian-mkdocs-publisher-template: Obsidian Mkdocs Publisher, a free obsidian publish alternative throught Mkdocs
• KosmosisDire/obsidian-webpage-export: Webpage HTML Export lets you export single files or whole vaults as HTML websites or documents. It is similar to publish, but you get direct access to the exported HTML.

Other interesting projects

• mathieudutour/gatsby-digital-garden: digital garden with Gatsby
• TuanManhCao/digital-garden: Free Obisidian Publish alternative

obsidian-publish-mkdocs's Issues

DataView support in obsidian-mkdocs

Hi,

As DataView is one of the most widely downloaded Obsidian plugins, is it viable to incorporate support into the the obsidian-mkdocs conversion template (either workaround or full solution?

I recently raised a request on the Obsidian forum about rendering DataView lists and tables on GitHub pages created with obsidian-mkdocs. See Rendering DataView Queries Results on GitHub Pages.

A workaround was proposed by opening the Developer Tools within Obsian and copying DIVs for the DataView lists and tables into the note. When the Vault is converted to GitHub pages the DataView lists and tables created from the copied DIVs render (see image), but the links don't point to the correct pages on GitHub. Clicking the links go to a 404 Error holding page.

In testing I found that the note Concepts/Creative Commons.md in the docs folder is found at <GitHubPageBaseURL>/<VaultName>/Concepts/Creative%20Commons/ on GitHub pages, but the links appearing in my converted list and tables created from HTML DIVs point to <GitHubPageBaseURL>/<VaultName>/<OriginNoteName e.g. DataView%20Test>/docs/Concepts/Creative%20Commons.md. The target url would need the <OriginNoteName>/docs/ string and .md file extenstion removed in order to work. Could this be automated?

math blocks in standard obsidian format doesn't render

For some reason my maths blocks doesn't render, however it does in obsidian. The standard way to write math blocks in obsidian is something like

paragraph
$$
maths
$$
paragraph

However I see that with this format the math blocks doesn't render in github either, so I change to the format

paragraph

$$maths$$

paragraphs

Now it renders correctly. However all my notes are written in the first style, there is a way to make that your template supports the use of the first format for math blocks instead of the second?

Mermaid diagrams are not rendering

Hello,
Issue visible on official demo:
https://jobindjohn.github.io/obsidian-publish-mkdocs/Features/Mermaid%20Diagrams/

Unfortunately I don't know how to make it work

adding additional plugins

attempting to add mkdocs-bibtex and mkdocs-timetoread and getting exit code 1 on deploy, for example:

ERROR    -  Config value 'plugins': The "timetoread" plugin is not installed
Aborted with 1 Configuration Errors!
Error: Process completed with exit code 1.

Is there a way to add additional plugins to root or fork of this (excellent) template?

First deployment does not look like template

Hi, I'm very new to this. I followed the steps outlined here and did not add or change anything but the deployed website looks nothing like the example template

Any idea what went wrong?

Mermaid is not rendering

Firstly, great project John! I wish I saw it earlier - I created 6 websites in Zola just to do the same thing.

Obsidian supports mermaid, but the current mkdoc output isn't.

graph LR
        A[Knowledge Representation] --> B[model]
        B--> C[Ontology]
        B -->D[Data model]
        A-->E[Classification system]
        E -->F[Taxonomy]
        E -->G[Subject classification system]

The fix to my knowledge is to add <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js" integrity="sha384-0yWn54pSGtfKCU+skfA69l25VsCw+MZt4LQov3xNRoS7YkAMrFokGgSBnAWSK4pv" crossorigin="anonymous"></script> or mermaid2 into plugins or

extra_javascript:
    - https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js

I have no preference, your choice.

how to create the index that contains preview and full page link of blogs?

i find this feature in https://squidfunk.github.io/mkdocs-material/blog/, it's more like a blog. i have tried "post_excerpt_separator: ", but it makes no effect.

No gh-pages branch

I have main, that's it. How can I add it if it isn't there?

Are insiders features supported?

I'm considering signing up for Material for MkDocs Insiders -- https://squidfunk.github.io/mkdocs-material/insiders/

Are Insiders features supported in obsidian-publish-mkdocs ?

Mermaids line color is too dark grey in dark mode

In the mermaids example, the connection line is dark grey in dark mode which makes the diagram is not readable. It looks fine in the mkdocs official documents.

Instructions to build locally using mkdocs

• provide requirements.txt also

New instruction required to the README regarding action permission.

I noticed that my CI initially failed due to a permission error. I had to navigate to Settings -> Actions -> General, scroll to the bottom and under workflow permissions I checked read and write access as well as the little box bellow that says "Allow github actions..."

No Theme?

I followed the instructions to set this up, but my site is loading with no theme.

Link here: https://sam1am.github.io/grimoire/
My settings:

I noticed the docs say to only copy the main branch, but then to publish a different branch, so I created the new branch.

Any ideas?

Publishing notes with images - securely

Thanks for this template. I discovered in an old published issue (in a fork, can't find it again) that to be able to use images in your posts, you need to move your Obsidian 'attachments' folder inside your repo folder. Otherwise, the images are not going be found in the published pages.

This works fine, but could be a security risk. For details and ways to limit the risks See my blog

Making the repo private is a no-go, it breaks the system. There might be other or better ways to fix this.

For now maybe you can mention this in README.md and add details about the location of images and the security risks.

Consitency of presentation between Material MkDocs and Obisidian

Hi, I seem to be on the same path as you with Obsidian and MkDocs. I was wondering what tools and tweaks you use to get the Obsidian previews working with the Material MkDocs syntax. Things like Admonitions/Call-outs use different syntax for example. Using Obsidian's syntax means it won't render in MkDocs when deployed and using MkDocs syntax means there is no preview in Obsidian.

Can i set style for a single page

eg: no search,navbar,sidebar for index page

Revisions not pushed

Having loaded the repo into Obsidi█n as a vault, and set GitPages to update from 'gh-pages', and GitHub Desktop by default pushing to 'main', revisions do not appear on GitPages after a push.

Alternately, on setting GitHub Desktop to push to 'gh-pages' instead it immediately notices revisions automatically made to files in the '.obsidian' directory. Commit-and-Push is unsuccessful because 1 Pull is pending for 'gh-pages' first due to remote revisions. GitHub Desktop is then unable to Pull either, citing, 'Unable to merge unrelated histories in this repository.'

I've retried anew several times, with occasional success pushing 'gh-pages' after Obsidi█n has added its contribution files to the vault. Upon 'gh-pages' being pushed, the files in the local vault directory are converted into .html files with the result that the original local files, though not the vault's directory structure, are no longer editable by Obsidi█n.

Perhaps I'm missing something very basic here.

[Edit: It's when GitHub Desktop is directed to address 'gh-pages' rather than 'Main' that the Markdown files are replaced with .html. Without directing it to address 'gh-pages' I'm unable to commit and push to GitHub, and when I do the files are replaced by .html and Obsidi█n cannot work with them. What am I missing?]

No way to put images from Obsidian on your webpage

I've used imgur as a workaround to this, I was wondering if it'd be possible to make a media directory for use in this.

ci.yml needs to be upgraded to Node 16

I've encountered errors with the ci.yml action.

It seems it needs to be upgraded to Node 16. I've made changes to my own repository and it works: https://github.com/cobylim/obsidian-check/blob/main/.github/workflows/ci.yml

I'm open to do a pull request for it as well if you prefer.

initial commit fails

Hi,

I'm using this with my class; thank you!

Some students are reporting that the generate from template fails on the initial commit. I just replicated for myself, and in the log I find:

remote: Permission to shawngraham/demo-hist1900-try3.git denied to github-actions[bot].

We can fix this by going to settings -> actions -> general, and then scrolling down to Workflow Permissions, and giving actions read and write permission, and permission to create and approve pull requests.

I think something must've changed at Github requiring this? I tested this all out before my class started last week and this wasn't necessary.

Change theme and colors

gh deploy --force error

I'm gettint an error after using the template to write my own docs.

Msg: remote: Permission to daniel-baf/URL-notas.git denied to github-actions[bot].
Error: Process completed with exit code 1.

error.txt

cname keeps getting wiped out

Each time I publish my site, I have to re-configure my custom domain in GitHub Pages.

Am I missing something?

"Troubleshooting MkDocs Feature Activation Issue"

Hi
I added a native mkdocs feature, but it's not showing up in the results.

theme:
  name: "material"
  features:
    - content.action.edit

It's not functioning as expected.
Best wishes

The action failed for me

6s
2s
Run mkdocs gh-deploy --force
INFO     -  MERMAID2  - Initialization arguments: {}
INFO     -  MERMAID2  - Explicit mermaid javascript library:
   https://unpkg.com/mermaid/dist/mermaid.min.js
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/runner/work/HE_Sr_Fellowship/HE_Sr_Fellowship/site
INFO     -  MERMAID2  - Page 'Mermaid diagrams': found 1 diagrams (with <pre><code='[language-]mermaid'>), converting to <div>...
INFO     -  MERMAID2  - Page 'Mermaid diagrams': found 1 diagrams, adding scripts
INFO     -  Documentation built in 0.46 seconds
WARNING  -  Version check skipped: No version specified in previous deployment.
INFO     -  Copying '/home/runner/work/HE_Sr_Fellowship/HE_Sr_Fellowship/site' to 'gh-pages' branch and pushing to GitHub.
remote: Permission to phoenixperry/HE_Sr_Fellowship.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/phoenixperry/HE_Sr_Fellowship/': The requested URL returned error: 403
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.11.2/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/mkdocs/__main__.py", line 280, in gh_deploy_command
    gh_deploy.gh_deploy(
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/mkdocs/commands/gh_deploy.py", line 127, in gh_deploy
    ghp_import.ghp_import(
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/ghp_import.py", line 283, in ghp_import
    git.check_call('push', opts['remote'], opts['branch'], '--force')
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/site-packages/ghp_import.py", line 119, in check_call
    sp.check_call(['git'] + list(args), **kwargs)
  File "/opt/hostedtoolcache/Python/3.11.2/x64/lib/python3.11/subprocess.py", line 413, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['git', 'push', 'origin', 'gh-pages', '--force']' returned non-zero exit status 128.
Error: Process completed with exit code 1.

Backlinks not loading

I'm not sure what I'm doing wrong but backlinks aren't working: site, repo.

The [[test] backlink should work, test.md is also in docs. Could you help? I'd provide more information but I have no inkling of what I'm doing wrong

Repeated problems adding stylesheet to mkdocs.yml

Hi. I keep encountering problems when attempting add...

extra_css: stylesheets/extra.css

...to the mkdocs file.

I've created the stylesheets directory and added the extra.css.

Repeatedly getting "run failed" messages after commit.

Another repeat error message that seems to have started after the above:

Here is the full yml doc:

Getting stuck

At this point I am lost:

5. Commit and push the changes. Github actions will take care of the rest, publishing your notes using MkDocs, with the Material theme.

I'm not sure what I have to do here. I've pushed the changes (added a "Test Doc" to the /docs folder in Obsidian), which are showing up on my GH desktop app, but not in the GH web browser repo.

6. Go to Settings > Pages and select the select the Source as your gh-pages branch.

No idea what this means. Settings in my account, in the repo?

Once all is done, I'm not sure where I'm supposed to find this published site on the web? What's the web address? Is one automatically generated through GH?

Basic markdown syntax issue

Thank you for issue #15. Having made the website I can see that basic syntax like highlighting using equals(=) symbol, underline using caret(^) symbol is not working as expected. I have made another page using this template as a test and there it seems to work. Attached are the images of the issue and the website is hosted here if needed

😞

😊

Thanks a lot.

Does not render latex preview

Mermaid diagram renders in Obsidian but not in MKDocs

Hi,

I've added Mermaid to the MKDocs configuration file mkdocs.yml as indicated on the material theme reference: https://squidfunk.github.io/mkdocs-material/reference/diagrams/

# Extensions
markdown_extensions:
  - footnotes
  # - attr_list
  # - pymdownx.arithmatex
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  # - pymdownx.details
  # - pymdownx.magiclink
  # - pymdownx.tasklist:
  #     custom_checkbox: true
#  - pymdownx.emoji:
#      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  # - admonition
  - toc:
      permalink: true

The Mermaid chart elements render in the local Obsidian instance but not on the site created with obsidian-publish-mkdocs.

Local

MKDocs site

Is there something further that need to be enabled or any changes required to the configuration for this to work?

Callouts are not displaying as they should

In new obsidian version, callouts work by default.

Here's an example:

> [!info] Referências
> - https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/How_CSS_works
> - https://developer.mozilla.org/en-US/docs/Web/Performance/Critical_rendering_path
> - https://developer.mozilla.org/en-US/docs/Learn/Performance/CSS

In the current template, they're displaying without format.

Here's an example:
https://biancapereira.github.io/bibi-garden/CSS%20backstage/Como%20o%20CSS%20funciona%3F/

LaTeX support

There is already a similar issue #10, but has no description(although it is obvious). To not reiterate the same thing, can I ask if it is possible to add LaTeX rendering support in this. I am a Research scholar and my notes heavily contains math equations, so it would be a great to upload notes using this template. Instead of a bug, please consider this as a feature request. Thank you.