Split README into smaller pieces.

[guettli]

The README is way to long and not pretty.

This tool could help: https://squidfunk.github.io/mkdocs-material/

https://github.com/guettli/static-site-generators

The winner is Hugo.

[guettli]

Or https://gohugo.io/

Maybe useful: https://github.com/adityatelange/hugo-PaperMod/

[zxenonx]

Hello sir @guettli,

How do you want the README to be split?

Maybe, I could help.

Thanks.

[guettli]

@zxenonx in the long run I would like to have nice pages and a feedback section for every note.

In the past I thought I need a structure like in a book:

Chapter 1 ...

Chapter 2 ....

But in the digital age, it might make more sense to have tags/labels.

so there is no hierarchy and no sorted order.

Every note gets an ID.

The tag/label approach would mean, that each note needs to be split into an own file.

In the file we need to specify the tags.

Most flexible would be key-value pairs.

Examples:

tag: testing tag: databases related: ID-of-other-note

---

But above are just my ideas.

What do you think? How could this huge page get split so that it is easier to read?

[zxenonx]

@zxenonx in the long run I would like to have nice pages and a feedback section for every note.

In the past I thought I need a structure like in a book:

Chapter 1 ...

Chapter 2 ....

But in the digital age, it might make more sense to have tags/labels.

so there is no hierarchy and no sorted order.

I entirely agree with this approach.

[zxenonx]

Every note gets an ID.

The tag/label approach would mean, that each note needs to be split into an own file.

In the file we need to specify the tags.

Most flexible would be key-value pairs.

Examples:

tag: testing tag: databases related: ID-of-other-note

But above are just my ideas.

What do you think? How could this huge page get split so that it is easier to read?

I was thinking about another structure... But I think your suggestion makes more sense. In fact, classification by tags, categories will allow to go directly to the information. And this theme https://github.com/adityatelange/hugo-PaperMod/ as you suggested is perfect for setting up such a structure. @guettli

[guettli]

ok. What could be the next step?

[zxenonx]

ok. What could be the next step?

Well, I'm going to try Hugo this weekend to familiarize myself with it.

Then I can get down to the real work.

Please, where do you want the site deployed? On Github pages or on a custom domain?

[guettli]

Please, where do you want the site deployed? On Github pages or on a custom domain?

I think I would use https://thomas-guettler.de/

[zxenonx]

Please, where do you want the site deployed? On Github pages or on a custom domain?

I think I would use https://thomas-guettler.de/

Ok. Great.

Last week, I built a dummy site with Hugo and PaperMod theme and deployed it on Netlify.

This weekend, I'll start the main work.

I assume we will be using this repo to host the docs. So I would need some access to push code. We'll use Netlify to host the site and link the domain to it.

[guettli]

@zxenonx great news! Sounds good.

My idea is to split the way too long text into "notes".

Next step from my perspective:

• Create directory "notes". There won't be subdirectories for categories. It is a flat namespace.
• Create three dummy notes. Each in an own markdown file.
• A build-script/makefile which can be triggered via github actions.

But wait a second. Maybe we have more posibilities if you create a simple django app. The source should be in git. But things like up/down-votes can't be managed with a static site.

Is there a common syntax for tagging in hugo? We could use the same syntax and parse it into a django model.

We should experiment with the prefered setup before settling on a solution.

[guettli]

@zxenonx I created a list for brainstorming the tags we could use. This makes more sense than a book-like hierarchical structure: https://github.com/guettli/programming-guidelines/issues/16

[zxenonx]

What a great idea sir!

In fact, we can build a Hugo static site inside a Django app to handle features like up/down-votes. I'll work on a POC as you have suggested.

Well, there's a common syntax for tagging in Hugo. @guettli

[guettli]

I think we don't need Hugo. At least not at the beginning. But we need a database schema.

[guettli]

I have seen on your github profile, that you already did something with django. I would use django and plain html, not hugo.

I think a model with name "Note" would make sense.

It has a slug. This is the filename from the git-repo. Example notes/foo.md will get slug "foo".

It has an attribute "text".

It has an attribute created_at and modified_at.

Then we need a simple view (function based view) which shows the markdown has html.

This would be first steps.

[zxenonx]

I have seen on your github profile, that you already did something with django. I would use django and plain html, not hugo.

I think a model with name "Note" would make sense.

It has a slug. This is the filename from the git-repo. Example notes/foo.md will get slug "foo".

It has an attribute "text".

It has an attribute created_at and modified_at.

Then we need a simple view (function based view) which shows the markdown has html.

This would be first steps.

Yeah, on the backend I mainly use Django & FastAPI.

I have noted note your suggestions and I will get on with it.

We'll talk about the tags management later, right?

[guettli]

We'll talk about the tags management later, right?

Yes, the first version does not need to support tags. Just the basics first. From markdown to html. I think this is the first task.