PR Question - Docs Contributions

[onkoe]

Hey there! I'm creating a PR that improves the documentation, mostly to expand/create explanations of certain topics for new users.

I have two questions:

1. Most documentation lines cut off around 90-110 characters. Is that on purpose? I've mostly seen Markdown use soft wrapping instead of line breaks in the same paragraph.
2. Are there any specific topics that anyone would like improved? 😄

Thanks for your support! ✨

[Keats]

1. No real reason, I just wrap manually to fit in the screen usually
2. A lot! I would like to re-do the docs based on something like https://diataxis.fr/ but there are potentially a lot of big changes coming up in future versions of Zola and I'm not sure whether this should wait for them or not

[onkoe]

Great, thanks for the detailed response!

1. Would you like me to continue the line-wrapping tradition, or would you be comfortable with soft-wrapping?
2. Diátaxis looks to be useful for new users! However, if Zola changes with tera2, it's likely better to wait. Until then, do you have any particular aspects of Zola that could use better docs? I'm happy to focus on areas you've seen folks have trouble with. 😄

[darrenmeehan]

I came to GitHub to update some documentation, as I had some trouble with linking to internal pages that I wanted to double check, but couldn’t easily find ann answer.

I think this page should cover how to handle internal links within a template. https://www.getzola.org/documentation/content/linking/

One aspect I think Zola docs could get better at is templating, even linking to Tera docs would be useful.

[Keats]

1. Yep whatever is working for you i don't mind
2. I think it could do well with some cross linking of features like @darrenmeehan mentions. Also ok to re-organise things, it's been growing steadily for many years without a change in structure.

One aspect I think Zola docs could get better at is templating, even linking to Tera docs would be useful.

Yeah not great right now. I didn't want to spend too much time on it since Tera v2 is "around the corner" but that's been the case since 2021 x)

[darrenmeehan]

Hi @Keats, I was wondering if I could split out built in functions into its own page?

https://www.getzola.org/documentation/templates/overview/#built-in-functions

[Keats]

They should probably all in a page but not in the overview