Blog system is overly complicated

tesar-tech commented 1 month ago

I have realized some drawbacks while creating a blog post.

I admit I might be wrong in some assumptions. In that case, correct me accordingly.

Issues

1. When one wants to create a blog post, there are many unnecessary actions to undergo.

Images are stored separately from the .md file. This makes it harder to work seamlessly because one has to have the links ready, but IDEs don't display the pictures when working with markdown.
A folder for every blog post can be avoided, simplifying the structure.
When committing changes, there are many more files than needed (more on this later).

2. There is a lot of repetitive information across the whole post creation process.

The published date and time are a good example. It's used in multiple places:
- Folder name for images
- Folder for the blog post
- Frontmatter in posted-on (in a different format) and in image-url
- Index.razor in the BlogEntries
Arbitrary folder and file names:
- The folder for images has no real meaning.
- The folder for the blog post is also arbitrary.

3. Generated code (in `SomeBlogPost/Code` and `SomeBlogPost/Examples`) is unnecessary to keep in the repository.

Is there a reason not to .gitignore them? What I have found so far:

These files can always be generated at build time.
It makes PR reviews harder (you have to sift through a pile of files you’re not really checking).
Line endings are messed up when regenerating the files on different systems, which pollutes the git status and has to be resolved locally.

Proposal

Let the generated files be where they should be.

The first step is to .gitignore them. The second step is creating a source generator and letting them live only in memory.

Simplify the blog post creation process (addresses issues 1 and 2).

Visual explanation:

BlogPosts
├── 2024-10-14_my-first-post.md
├── 2024-10-10_another-great-article.md
├── 2024-10-08_yet-another-post.md
├── 2024-09-30_new-insights-in-tech.md
├── 2024-09-25_exploring-net-core.md
├── media
│   ├── 2024-10-14_my-first-post
│   │   ├── image1.png
│   │   ├── image2.jpg
│   │   └── diagram.svg
│   ├── 2024-10-10_another-great-article
│   │   ├── infographic.png
│   │   └── screenshot.jpg
│   ├── 2024-10-08_yet-another-post
│   │   ├── illustration1.png
│   │   ├── chart.png
│   │   └── icon.jpg
│   ├── 2024-09-30_new-insights-in-tech
│   │   ├── tech_diagram.png
│   │   └── photo.jpg
│   └── 2024-09-25_exploring-net-core
│       ├── architecture.png
│       └── screenshot1.png

One folder, let's call it BlogPosts
Blog post naming: YYYY-MM-DD_url-of-the-blog-post.md. This addresses several issues:
- We have a meaningful filename. The publish date will be parsed out of it and not mentioned elsewhere. The same goes for the URL.
- No need for a separate folder for each post.
The BlogPosts folder will also contain a media folder, where every image will be placed in a subfolder named YYYY-MM-DD_url-of-the-blog-post. The advantage of this approach is that it aligns with how VSCode (and probably other markdown editors) handle pasted images (they save them in media/filename folder). It's also more straightforward to copy the media folder.
Images are now part of the content.

Opinions?

stsrki commented 1 month ago

All valid comments. But, it would only work for a portion of it. There are places where we could improve the experience.

We create a separate folder for every blog so that everything is grouped together. If we were to use a YYYY-MM-DD_url-of-the-blog-post.md for all blogs in a single folder, where would examples and code samples go? They would still have to be separated somewhere. So by making them each separated by folder, and by date/arbitrary name, we have a way of easily finding them in the solution explorer.

Examples and Code but be part of the source control because they must be part of the runtime also. And they must be there when the app is built. We don't want to build them every time.

I agree with the polluting the git status comment. We could improve that. But even that is not a problem since as soon as you stage the changes, git will figure it out and remove those files.

Regarding the media files. They must be placed in the wwwroot. Only from there can they be served. Maybe we could make another build process that could copy them from media/filename folder into wwwroot. If we would go that route. Not sure TBH.

tesar-tech commented 1 month ago

Separate folder

The generated files all have unique names, why do we need to keep them in separate folders? For the Index.razor file it's a different, but we can make it YYYY-MM-DD_url-of-the-blog-post.razor. Or (even better idea): we can easily replicate the current structure, just not in the same location as the markdown files.

Examples and Code folder

Excluding them from vcs will not cause building them every time. Only every time someone new clones the repo or when the site is build and deployed. I am not familiar with the deployment system, but I guess it doesn't happen so often. Correct me if I am wrong, but the current build "script" that will generate the Examples and Code is being run before the project is build, so not having Examples and Code before build time isn't really an issue (??)

Media files

Easily done by

      app.UseStaticFiles(new StaticFileOptions
        {
            FileProvider = new PhysicalFileProvider(Path.Combine(Directory.GetCurrentDirectory(), "..","Blazorise.Docs", "Pages","Blog", "media")),
            RequestPath = "/media"
        });

And then this ![alt](media/somePost/img.jpg) will work. No need to create build scrip and move it somewhere else.

Megabit / Blazorise