docs: zensical based docs

[CommanderStorm]

This PR migrates us from markdown for Material to its successor project.
As discussed in slack a while a go, material has been discontinued and this is now zensical.

I have not experienced any issues and have looked at every page we offer here

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.70%. Comparing base (2aac6f2) to head (1a40327).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1394   +/-   ##
=======================================
  Coverage   93.70%   93.70%           
=======================================
  Files         111      111           
  Lines        4387     4387           
  Branches     1389     1389           
=======================================
  Hits         4111     4111           
  Misses        276      276           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Size Change: 0 B

Total Size: 134 kB

ℹ️ View Unchanged

Filename	Size
dist/index.cjs	67.5 kB
dist/index.mjs	66.4 kB

_{compressed-size-action}

[HarelM]

I prefer to simplify the setup and wait a bit longer for the following feature to land:

• Official Docker image zensical/backlog#58

Otherwise, running this locally can be a bit of a hassle.
Since most of the changes here are in the readme and not in the code, I'm good with waiting for it to mature a bit more...

[louwers]

I think it is easier to install Python than Docker. Also Docker is not very performant on macOS. So I would prefer this approach.

I noticed that the interface shifts slightly when a page with a sidebar is opened. Will report that as a bug.

[HarelM]

It's still easier to install Docker than python and rust and go and java all together, not to mention maintaining the right version per the relevant tool you need to run.
Docker is the defacto dev container for a good reason...

[louwers]

@HarelM You don't need Java, Rust, Go or Rust, right? I think you just need uv, it even installs the right Python version if it is not available on the system.

Please try it out, I know managing Python dependencies used to be a nightmare, but it has gotten downright pleasant since uv came to the scene.

[birkskyum]

i just ran it. Installed uv took few seconds, and then pnpm run docs, and that was it - very smooth experience

[HarelM]

I maintain a lot of projects on my machine, and every time I need to install something globally I fear that I will break another project I'm working on.
Docker solved this problem for most parts, especially for command line tools like this one, I don't see a reason to rush into migrating to zensical and installing anything else besides Docker (and unfortunately nvm as this is mainly a typescript project). We can wait for a docker image for this "side" feature, and probably other fixes that should be coming as other people migrate to it.
There's no security risk here and no real pressure to move.
Don't get me wrong, I do think we should move, but not right now. This can wait a bit.

[HarelM]

I honestly think this is a mistake at this point in time, but I guess I'm the minority. You are welcome to push this forward @CommanderStorm.

[birkskyum]

can we add a Dockerfile, so it's possible to run in container if preferred?

[louwers]

uv doesn't install anything globally. Well, except that it has its own global cache (which makes it really fast). For what it is worth, it got an 'Adopt' rating from the Thoughtworks Technology Radar and is probably one of the most loved tools in the Python ecosystem.

@HarelM Could you try it out and think about it a little, then if you still don't like it, we can wait and go for a Docker-based approach. But I think you will like it. It's much faster and a nicer experience to use zensical (a native Rust based CLI tool) directly without Docker.

[birkskyum]

I added Dockerfile/docker-compose.yml, which is executable with docker compose -f docs/docker-compose.yml up --build from repo root.

[HarelM]

can we add a Dockerfile, so it's possible to run in container if preferred?

As far as I read they are currently not accepting pull request due to high changes rate (if this is not a red flag I don't know what is).
I've linked to a roadmap item in zensical to add a docker image.
The issue is only 2 weeks old.
I think we can wait for it for a month and see if it happens or not.
There's also a discord channel if you're interested to ask when is this planned, I don't have the bandwidth to visit there unfortunately.

The fact that this required as change in the CI to support this is less than ideal, but again, I'm the minority here, so you are welcome to do it without my blessing.

I see too many red flags to support this, it's not about tooling, it's about maturity, and I think we are rushing it for no good reason, or at least I haven't heard one in this thread.

[HarelM]

I added Dockerfile/docker-compose.yml, which is executable with docker compose -f docs/docker-compose.yml up --build from repo root so that's an option.

Yey, more cleanup will be needed later on that no one will remember to do...

[louwers]

I see too many red flags to support this, it's not about tooling, it's about maturity, and I think we are rushing it for no good reason, or at least I haven't heard one in this thread.

Agree with this.

That said, when we eventually do make the switch, I believe we should drop the Docker by default approach.

[HarelM]

I believe we should drop the Docker by default approach

I'll be happy to discuss this, but not here, as I completely disagree. But that is out of scope of this PR, as the main reason for this PR is zensical.

[CommanderStorm]

I believe we should drop the Docker by default approach

I'll be happy to discuss this, but not here, as I completely disagree. But that is out of scope of this PR, as the main reason for this PR is zensical.

From what I understand, the main motivation for using Docker is to avoid installing local dependencies. In this case, though, nothing extra needs to be installed - Python is already available, and UV is widely used in the Python ecosystem.

If we applied that reasoning consistently, we’d also be using Docker for npm, right? 😉
I actually didn’t have the correct npm version installed, so I had to adjust my setup specifically for this repository.

I’m always happy to submit PRs when there’s a defect or benefit, but at the moment, I don’t see that here.
If we want to move into this direction anyhow, we might as well don it now..

[CommanderStorm]

Plus the sidebar looks more modern 😋

[HarelM]

I'm having a hard time merging something with the following statement in the docs:
https://zensical.org/docs/community/get-involved/