Continue or deprecate the template?

[Mara-Li]

Hello everyone,

I hope you're all having a great month so far.

I'm reaching out because I need your help and advice. Lately, I've been considering abandoning the current template (not the plugin!).

Why? Well, maintaining the template has become quite challenging for several reasons:

• Working with Mkdocs is cumbersome and time-consuming. Personally, I find it difficult and frustrating, whether it's making plugins or just fixing issues. Consequently, there's a heavy reliance on JavaScript within the template.
• Updates to Material often require a subscription, which is understandable as developers need to earn a living. However, many of these updates end up replacing my own work, such as the page preview feature. I worry that in the future, none of my contributions will be necessary as everything will be integrated directly into the template.
• I've never been fully satisfied with the template; I feel it lacks certain customization options available in other templates.
• The build process is incredibly lengthy. As mentioned before, dealing with Mkdocs is not something I enjoy, and the long build times only exacerbate my frustration.
• Additionally, I have a preference for Typescript over Python, which Mkdocs relies on.

Recently, I've been working with Quartz and I've grown to love it more and more. The only downside is its lack of mobile support. However, I've made some modifications to a private template to address this issue and have added file/folder icons. You can view my website here: https://www.mara-li.fr/.

Quartz offers numerous features, is already compatible with Publisher, and boasts a vibrant community dedicated to enhancing the template.

If I decide to transition to Quartz, I'll need to:

• Develop workflows to facilitate updates from my own code snippets. I've done this before with the old template and know some methods to synchronize everything.
• Remove all documentation and references to the old template. While not particularly difficult, it will be time-consuming, and there's a chance of overlooking some typos.

I'm truly enthusiastic about Quartz and the supportive community surrounding it. I want to further integrate Publisher with Quartz.

However, since you're all users of Publisher, I value your input, ideas, and possibly even your willingness to collaborate on maintaining the template with me (or independently).

If nobody is interested in maintaining the template, here's what I'll do:

• Transfer the documentation and rewrite it as a V2, removing all mentions of the old template. The V1 documentation will remain accessible.
• Clearly state on all repositories that the template is now in maintenance mode only, with only essential PRs being merged. While I'd prefer to archive it (as archived repositories have an icon), I believe people may still wish to continue maintaining and fixing it.

[nickpunt]

Hi there, thanks a ton for building the plugin, it really is a kindness that you're putting in the time to support something for the community, and I know the OSS community doesn't hear this enough! I can only answer this from my limited POV, so here goes:

I'm a new (potential) user that found Publisher after I found Quartz, so I have no particular interest in mkdocs. My interest is something that is brainless / nearly turnkey, with the option to tweak under the hood if something isn't to my liking. Fwiw I'm technical and a frontend designer but not an engineer accustomed to devops backend etc, and not deep in the plugin ecosystem to understand its nuances. I use Obsidian Publish today and it's not customizable enough for frontend dev, which is why I'm interested.

I tried out Publisher a week ago, and it was challenging because there were tons of options that seemed unnecessary for a basic Quartz setup. There's a ton of jargon that the plugin assumes the user understands, and several places where what is being talked about must be inferred. There's also what appear to be many options that are unrelated, or at least I do not have confidence that they are appropriate for what I want. After an hour I was able to get Publisher working, but I still don't have a high degree of confidence in whether I did it right (important for anything file-related), and so I've stopped using it for now. I anticipate picking it up again in the next month or so to continue my investigation.

If you're to focus Publisher more on supporting Quartz, I might recommend looking more closely at improving the broad accessibility of the Publisher, e.g. limiting the number of setup steps, picking really good defaults, and hiding all non-essential options behind 'advanced' menus. This would go far in making the plugin better for beginner users. I think there's a lot of efficiency & clarity that can be gained if you're just focusing Publisher specifically on Quartz as a primary publishing target, because a lot of assumptions can be made about what the user is trying to do (vs generically supporting lots of options). Not sure that's the direction you're thinking but personally that's what I'd love to see, and I think it'd make it easier for a lot more users to adopt.

Best of luck in the journey ahead on this, and thanks again for the hard work putting this together!

[Mara-Li]

Sadly, Publisher is like my ADHD brain : messy.

I tried a lot for a better accessibility, but I don't have enough return of user for what I need to do for a better understanding. Everything is my own works and what I need and want.

Some options was asked by user and I added them because, they needs them.
Publisher was always "template agnostic" in mind. The goal was to allow EVERYTHING.

By the way, there is a preset option where you could download the settings of some user and they are two for quartz. Give it a try!

[TheBestPessimist]

Maybe my understanding is wrong, but after reading your text, i am left with the opinion that you would feel better if you were to work with Quartz in the future.

I think this might also make the plugin space better, because work will not be duplicated, so instead of everyone wasting their time and reinventing the same wheels again and again in different technologies, they are instead building a better and cohesive product for publishing.

My conclusion is that if Quartz sounds better to you, move Publisher to Quartz and deprecate the rest. This will probably help the Quartz project too, as you could add features there directly!

[Mara-Li]

I deprecated the old template don't worry! :)

[didiowen]

Hi Mara,

I'm very new to Enveloppe and used this template to publish some of my notes. However, I'd really like to integrate the hooks (strip_comments and fix_heading) you provided into my MKdocs. Is it achievable by just copying the overrides folder and mkdocs.yml content?

[Mara-Li]

Yeah, normally. But my memories are blurry so im not 100% sure though

[ooker777]

Sorry for not participate this earlier. You have already made the decision, and I think it's the right choice. Your rationale sounds good to me.

If you find Quartz fits you, go ahead. I know it has a good community, and the docs is helpful too. For me, its biggest drawback is that it uses Node, which isn't as convenient as Deno. Deno was created specifically to fix problems that Node cannot fix itself, and both are created from one author. See this talk 10 Things I Regret About Node.js - Ryan Dahl - JSConf EU. While Deno indeed has a smaller community, I think that's suffice for a digital garden. You only need a bicycle of the mind, not an aircraft. And for the SSG framework for Deno I use Lume, which has a _data.yaml model that has better developer experience and be more flexible than the quartz.config.ts file. So I think it's worth to take a look at it.

[Mara-Li]

If you made a template that allows to use everything from Obsidian (hello wikilinks and translucent), don't hesitate to share it.
TBH I prefer bun, that is compatible with Node ;)

[ooker777]

I haven't tried Bun as I think its main focus is speed, not DX. And its community is smaller than Deno. But of course I'm just sharing my thought, not to convince you to switch.

I don't get why wikilinks is a problem, as the plugin converts it already. Translucent? I don't get why it should be in the template. In general, as the job of the plugin is to convert Obsidian flavored markdown to github flavored markdown, I'm not sure what template we need? Your Quartz or Mkdocs templates to me are bug and feature fixes that a regular Obsidian user will expect to have, like graph view, callout. Am I correct?

[Mara-Li]

For the last part, yes.
The plugin allows to send everything everywhere, so ok for any site.

For me, a good template/site must have at last the same feature than Publish (if not, they are not an alternative), that's why Wikilinks (even I convert them), translucent, callout and graph view are important (a little less for the graph view).

[ooker777]

Not sure what you mean by translucent. It's a feature for the browser, not website. Or do you mean dark mode?

[Mara-Li]

By translucent I mean "preview on hover", sorry.
I also think about embedding file as a feature a template must have