Is there a template repo or possibly a sample repo?

[AgedLace]

I have attempted to create a test site based upon your documentation. When I run a local server, I got a LOT of errors along the lines of

"Traceback (most recent call last):
File "/home/deb/.local/bin/mkdocs", line 8, in
sys.exit(cli())"; last one is "ModuleNotFoundError: No module name 'material'

FYI - I modeled my mkdocs.yml after the one that is in your repository.

Thank you.

[mkusz]

Have you installed Material for MkDocs? It should be automatically installed within publisher since it's a dependency, but maybe there is some other error? Can you share your mkdocs.yml and output of pip freeze?

As for template repo, etc. I'm working on that. Also, I'm working on a debug plugin, that will help with this kind of errors in the future.

[AgedLace]

I didn't realize you had made a template repo! THANK YOU ... I've been able to get a test vault working locally. Going to play with your template, then when things are running smoothly, I'll need to find a gh-pages workflow. I am SO happy I found your repo! It has EVERYTHING I've been looking for to organize and publish my obsidian vault online except for the gh-pages deployment.

I am SO grateful! Thank you!

[AgedLace]

I've been spending days on this and am hitting my head against the wall. Here are the error messages I'm getting when I execute both "mkdocs serve" and "mkdocs build".
Note - I've doublechecked my two files that it says are missing 'status', but status is defined in the metadata. In fact, I used a template to set up the docs to be exactly like the documents in other directories. I don't know where to go from here.
I really wanted to make this work. :(

INFO - Building documentation...
INFO - Reading meta data from "README.md" files
WARNING - Missing "status" value in file "1st Level Subdirectory/1st level sub doc.md". Setting to default
value: "published".
WARNING - Missing "status" value in file "root-document.md". Setting to default value: "published".
INFO - Draft directories: ['Blog', '.obsidian', 'Templates']
INFO - Draft files: []
INFO - Hidden files: []
INFO - DeprecationWarning: read_text is deprecated. Use files() instead. Refer to
https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration
advice.
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs_publisher/blog/translate.py", line 25, in
_read_lang
lang_yaml = importlib.resources.read_text(lang_resources, f"{self._config.lang}.yaml")
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 18, in wrapper
warnings.warn(
INFO - DeprecationWarning: open_text is deprecated. Use files() instead. Refer to
https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration
advice.
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 80, in read_text
with open_text(package, resource, encoding, errors) as fp:
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 18, in wrapper
warnings.warn(
INFO - Parsing blog posts from 'Blog' directory
Traceback (most recent call last):
File "/home/deb/.local/bin/mkdocs", line 8, in
sys.exit(cli())
^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/click/core.py", line 1157, in call
return self.main(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/click/core.py", line 1078, in main
rv = self.invoke(ctx)
^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/click/core.py", line 1434, in invoke
return ctx.invoke(self.callback, **ctx.params)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/click/core.py", line 783, in invoke
return __callback(*args, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs/main.py", line 270, in serve_command
serve.serve(**kwargs)
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 86, in serve
builder(config)
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 67, in builder
build(config, live_server=None if is_clean else server, dirty=is_dirty)
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 277, in build
config = config.plugins.on_config(config)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs/plugins.py", line 527, in on_config
return self.run_event('config', config)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs/plugins.py", line 507, in run_event
result = method(item, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs_publisher/blog/plugin.py", line 56, in on_config
parsers.parse_markdown_files(
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs_publisher/blog/parsers.py", line 64, in parse_markdown_files
post: frontmatter.Post = frontmatter.load(markdown_file)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/frontmatter/init.py", line 150, in load
return loads(text, encoding, handler, **defaults)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/frontmatter/init.py", line 165, in loads
metadata, content = parse(text, encoding, handler, **defaults)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/frontmatter/init.py", line 82, in parse
fm = handler.load(fm)
^^^^^^^^^^^^^^^^
File "/home/deb/.local/lib/python3.11/site-packages/frontmatter/default_handlers.py", line 238, in load
return yaml.load(fm, **kwargs)
^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.11/site-packages/yaml/init.py", line 81, in load
return loader.get_single_data()
^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.11/site-packages/yaml/constructor.py", line 49, in get_single_data
node = self.get_single_node()
^^^^^^^^^^^^^^^^^^^^^^
File "yaml/_yaml.pyx", line 673, in yaml._yaml.CParser.get_single_node
File "yaml/_yaml.pyx", line 687, in yaml._yaml.CParser._compose_document
File "yaml/_yaml.pyx", line 731, in yaml._yaml.CParser._compose_node
File "yaml/_yaml.pyx", line 847, in yaml._yaml.CParser._compose_mapping_node
File "yaml/_yaml.pyx", line 860, in yaml._yaml.CParser._parse_next_event
yaml.scanner.ScannerError: while scanning a simple key
in "", line 3, column 1
could not find expected ':'
in "", line 4, column 1

[mkusz]

Hi @AgedLace ,
Sorry for late reply, but I just simply missed the notification about your answer 😞
Can you please try to install "publisher" from dev branch?
There are some elements that could help:

• python-frontmatter library is removed from dependencies
• there is a fix for deprecation warnings
  There is also a new debugger plugin, but let's play it slowly. You can try to find me over Obsidian Discord channel (maciejkusz), so it could be easier to solve it "on the fly" if you will have any new problems.
  PS. This dev branch should become release by the end of this week.

[AgedLace]

Hey there! VERY glad to hear from you!!!

There's no hurry ... I'm not techie enough to figure out how to install publisher from dev branch.

I can wait until you push the release later this week.

I'm just so VERY glad that this project is still active! It's always been my first choice.

THANK YOU!!!

[mkusz]

Installation from branch looks like this:
pip install git+https://github.com/mkusz/mkdocs-publisher.git@dev
But if you don't want to try, don't worry. I'm just polishing some stuff in documentation and should push it within a few days.

[AgedLace]

Thanks! I'll just wait ... I feel more comfortable with that. Again, I'm in no hurry. I have something that works at the moment, but will be able to move it over to this when the time comes.

Again, THANK YOU!!!

[AgedLace]

Hello @mkusz !

I found some time to test this from the dev branch as I thought it might be helpful to you with troubleshooting and feedback.

I've made a test repo here - https://github.com/AgedLace/test-mkdocs-publisher

Still have the deprecation warnings, and I had to turn strict mode off. Below is a copy of my terminal log.

---

INFO - Building documentation...
INFO - Reading meta data from "README.md" files
INFO - Draft directories: ['blog', '.obsidian', '_templates']
INFO - Hidden directories: []
INFO - Draft files: []
INFO - Hidden files: []
ERROR - en
INFO - Parsing blog posts from 'blog' directory
INFO - Creating blog posts index files
INFO - DeprecationWarning: read_text is deprecated. Use files() instead. Refer to
https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration
advice.
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs_publisher/blog/creators.py", line 188, in
_render_and_write_page
index_template = importlib.resources.read_text(templates, "posts-list.html")
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 18, in wrapper
warnings.warn(
INFO - DeprecationWarning: open_text is deprecated. Use files() instead. Refer to
https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration
advice.
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 80, in read_text
with open_text(package, resource, encoding, errors) as fp:
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 18, in wrapper
warnings.warn(
INFO - Reorder blog posts from newest to oldest
INFO - Cleaning site directory
INFO - DeprecationWarning: path is deprecated. Use files() instead. Refer to
https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy for migration
advice.
File "/home/deb/.local/lib/python3.11/site-packages/mkdocs_publisher/_shared/resources.py", line 16,
in add_extra_css
with importlib.resources.path(
File "/usr/lib/python3.11/importlib/resources/_legacy.py", line 18, in wrapper
warnings.warn(
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
- blog/blog-post2.md
- blog/blog-post3.md
INFO - Removing blog posts pages and section from direct navigation
INFO - Removing blog sub index pages from navigation menu
INFO - Parsing backlinks
INFO - Documentation built in 0.63 seconds
INFO - [07:05:59] Watching paths for changes: 'mkdocs.yml', 'docs'
INFO - [07:05:59] Serving on http://127.0.0.1:8666/
INFO - [07:06:03]

---

Also, I have created 3 test blog posts, but only the first one is recognized. I have double checked that their status is set to published. The rest of the repository seems to be working as intended. I see from the above terminal log that they are somehow not included in the 'nav' configuration. It was my understanding that pub-meta took care of this automatically?

Thank you again for your time and effort in creating this. It is very useful!

[mkusz]

Hi @AgedLace,

Thanks for your report because it's very helpful. Also an example git repo (maybe you can add me as an editor/contributor, so I can create a branch and push to it some changes whenever it's needed?).

But let's get back to the main topic. As for deprecation warnings, I have pushed new version to my dev branch (previously missed some usage of the old importlib library api). To try it out, you have to execute the following command:
pip install --force-reinstall git+https://github.com/mkusz/mkdocs-publisher.git@dev

As for missing blog posts, there is a problem on your side (but to be honest it's also a bug, I have added to solve to the backlog). The problem is with date format used in the blog posts:

• first of all you should use format with and hours like this date: 2023-08-27 21:30:00
• second thing is that posts cannot have the same exact date, because algorithm solving posts order will not work
  To fix it, you have to edit date field in posts to have proper date format and different values and it will start to work.

There are also some other smaller issues in yours mkdocs.yml file:

• in theme you have defined 2 scheme but they need to start with - because they are a part of the list,
• you didn't defined site_dir but this is a bit deeper problem (not yet described in my project documentation). This problem is related to setting up GitHub Pages in the feature. To fix it you have to do some changes in the repo:
• rename directory with the documentation to something like documentation,
• update mkdocs.yml with those 2 values:

docs_dir: documentation
site_dir: docs

Why? GitHub Pages can be configured to use content created by MkDocs, either from:

• docs directory (cannot be changed, but it's simpler solution),
• any branch (much harder to setup, since needs some additional GitHub Actions to make it fully automated).
  Both solutions will be described after release of v1.1.

Final thing. Yes pub-meta is created for handling nav creations. As a pro tip, try to utilize (when needed) order of directories by adding some digits into their names and add some README.md file with values for slug and title to preserve "human readable" values (project repo utilize that approach).

Hope it helps. If you have any other problems/questions don't hesitate to ask. I really like this kind of interactions and it helps me with project development and fixing some issues and understand where project documentation is lacking and what should be described more clearly or just added.

PS. In mkdocs.yml you can also add, a new plugin called pub-debugger that will create a log and zip file, so you can share this zip file with me and I will include most of the details related to build status and installed libraries.

[AgedLace]

Okay ... I have sent you an invite to be a contributor to the repo.
THANK YOU for the very detailed response. I will try to work through these things on my end tomorrow. I'm glad what I posted was helpful. I'm glad I am able to contribute in some small way.

I will work through the things you've shared, if I come across something I don't understand, I will let you know.

THANK YOU!!

[AgedLace]

I executed the command you gave me above ... here is the pasted portion of my terminal log ...

---

Attempting uninstall: mkdocs-publisher
Found existing installation: mkdocs-publisher 1.1.0
Uninstalling mkdocs-publisher-1.1.0:
Successfully uninstalled mkdocs-publisher-1.1.0
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
yt-dlp 2023.7.6 requires mutagen, which is not installed.
yt-dlp 2023.7.6 requires websockets, which is not installed.
pikepdf 8.2.3 requires deprecation, which is not installed.
obsidian-blog 0.2.2 requires watchdog<3.0.0,>=2.1.6, but you have watchdog 3.0.0 which is incompatible.
Successfully installed beautifulsoup4-4.12.2 certifi-2023.7.22 charset-normalizer-3.2.0 click-8.1.7 colorama-0.4.6 ghp-import-2.1.0 idna-3.4 jinja2-3.1.2 markdown-3.4.4 markupsafe-2.1.3 mergedeep-1.3.4 mkdocs-1.5.2 mkdocs-material-9.1.21 mkdocs-material-extensions-1.1.1 mkdocs-publisher-1.1.0 packaging-23.1 pathspec-0.11.2 platformdirs-3.10.0 pygments-2.16.1 pymdown-extensions-10.1 python-dateutil-2.8.2 pyyaml-6.0.1 pyyaml-env-tag-0.1 regex-2023.8.8 requests-2.31.0 six-1.16.0 soupsieve-2.4.1 urllib3-2.0.4 watchdog-3.0.0

---

do I need to install / update those programs through pip? Or is it more complicated than that.

In case you need the info, I'm running a Linux distro called Manjaro on my desktop. It is a derivitive of Arch Linux.

Thanks!

[mkusz]

Have you solved those issues?
If not, are you using virtual environment?
What IDE (pycharm, vscode or pure terminal experience) are you using?
It seems like you have some conflicts due to global/system wide package installation and this can be solved by using mentioned virtual environments like venv.

[AgedLace]

No, I have not solved these yet, that I know of. I've tried using virtual environments before. It ended up really corrupting my system (especially python, and programs relying on it) and I had to do a clean install.

[mkusz]

Probably you have made some mistake since virtual envs are specially designed to prevent mixing python libraries from projects (like this one) and one from system.
Probably the easiest approach is to manage projects over pycharm and create separate venv for each project and then remove all not needed libraries from system (like obsidian-blog and yt-dlp).

[AgedLace]

That sounds a bit over my head techy wise ... however ... I will research this some more and look into it. Perhaps I'll create a VirtualBox VM and play around with it there so as not to corrupt my system again.

THANK YOU for your time and help!!!

[AgedLace]

I think I've made all the changes you suggested and pushed to my test repo. Generated two debugger logs. Attaching below.
20230827_195632_mkdocs_build.log
20230827_195632_mkdocs_debug.zip

[mkusz]

Yes, I saw it, but in general you should not push them to the repository since any build will recreate those files. You should delete them, push changes to the repo, then create a .gitignore file with the following content:

*_mkdocs_build.log
*_mkdocs_debug.zip

[mkusz]

From the log file and after pulling your repo, it seems like the build process is working right now. If you have any other questions, please let me know ;)

[AgedLace]

Awesome! THANK YOU! When I get a chance later this week, I will play around with this some more. I am mindful this is still beta, but I'll be working on creating the vault and blog that I want to eventually publish.

Just would like you to know that should you need more testing - I would be willing to help in any way that I can.

I appreciate very much the time and effort involved to create such a project, and I am grateful!

[mkusz]

If you will have any other problems, found some issue or just have an idea for new functionality or some improvement, you know where to find me ;)