766f6964 / mublog Goto Github PK

In python file, we should be able to define a base url. Because everybody wont post their content on '/'. For example, me.

Summary:

Normally, pages are generated by converting the content in their respective md files into html, and then filling it into the page template.
For normal pages this is done, but we forgot that for articles and tags pages.

I think this program should support dark mode. A toggle switch would require JavaScript so a change in the python file, or even better, creating a config.yml file with more customization options would be great.

Summary:
Originally, I developed this project in shell script with the intention to have it just work everywhere, without any major dependencies.
However, this has a couple of problems:

1. The code because harder to maintain, with additional features.
2. We already have a hard dependency with pandoc, so the no-dependency argument doesn't really hold.
3. Writing this in python will save a lot of development time.
4. The code becomes more portable

After reading the code-review by KubaO, I decided it is a good idea.
Work on a proper python implementation has started, and will be published over the coming days.

Summary:
With μblog supporting more features, the complexity of the project also increases.
The goal always has been to be a very minimal blog site generator, that also provides some quality of life features, that the user can enable, if he wants to. This freedom of choosing what functionality to include in your build results in many different possible configurations. One user might use dark theme instead of light, but doesn't want tag support. But he does want a table of contents, while another user might not. Supporting all this customization means a lot of different conditions that will apply to the templates.
If a user wants to disables certain functionality, say, tag feature, all the relevant code should be stripped out of the generated .js and .css files. Mix-matching all these customization options makes it tricky not to break anything
In short: Many different configurations that need to be enabled in a single .js/.css/.html file quickly become unmaintainable.

Possible Solution:
So, what can we do, to make this better?
Instead of having one large .js/.css file where we enable/disable section with different flags, it would be better to break up all functionality in very small, mostly atomic (where possible) feature-fragments. Each feature-fragment should be mostly self-contained.
We could then utilize a tempting library or the python inbuilt library that only pieces together the relevant feature-fragments.
This is not a perfect solution, since we would still have conditions when to insert which feature-fragment.
However, it would split up the complexity from one big file into smaller, more simple and easier to maintain files.
Implementing this would require significant refactoring in the code-base, but I feel that it would be beneficial in the long run, and make implementing new features easier.

Summary:
Currently we try to align the table with with the width of a post, using overflow-x: auto;.
However, if the table is to large (has to many colums), an overflow still happens, causing an ugly layout break:

To solve this, we wan't to automatically make the table scrollable horizontally, if an overflow would happen.

Summary:
Currently the error messages are not very descriptive, and also they can easily get drowned under all the verbose logging.
This could be improved with some color codes for error messages.

Summary:
It would be nice to have support for tags, to allow reads to filter blog posts. This is especially helpful if a blog has many posts, and we would like to read a post, that about similar topics to the one we are currently reading.
The source post files already require a header field for tags tags: tag1, tag2, tag3 etc, but currently they are unused.

Adding support for tags requires multiple changes:

1. We want a navigation tab for all tags of all posts. Each tag on that page should be in a bubble, with a number suffix/prefix, indicating how many times this tag was used. This could look similar to this:

(Taken from https://blog.washi.dev/tags/)

2. We should display the tags of a post at the bottom of the post.
3. To filter the tags, JS is required. And we need to figure out, where we want to display the list of filtered posts. (On the article tab, or the tags tab..?)

Summary:

When the codebase got cleaned up a bit more, and there won't be any major changes to the structure of the code, every function should be properly documented (description, parameters return type etc).

Summary:

It would be nice if μblog provides its own 404 page, that the user can customize.
That way, when μblog is deployed, and a visitor tries to follow an invalid link, we can link to our our custom 404 page.
This keeps the look of μblog consistent, and allows the visitor to navigate back to the main/article page(s) etc.

Summary:

We already define most of the path values in the config class. However, in some places in the script, and also in the templates, we utilize hard-coded values like "posts/" etc. This should be fully avoided, so that the user can chose custom directory names or paths in the config, without the script/site breaking.

This essentially just means, the path variables need to be tidied up a bit, and in the places where we currently have hard-coded path/directory/file names, need to be replaced with the variables.

Summary:

It would be a cool idea to print a short summary of the build process, e.g. how many posts were processed successfully, how many were skipped.

Summary:

Currently, every-time the script is executed, all blog posts are rebuilt (except the ones that have the ignore prefix).
While this is okay if the blog only has a couple of posts, the build times get pretty long when a user has hundreds of posts.
This is especially annoying if you just want to rebuild to if some of your changes look good on the page. Or if you fix a typo, and you need to wait minutes just for rebuilding. We can do better!

Suggestion:

We want to keep things simple, and not introduce a bunch of new dependencies.
All that is needed, is to create a "database", that maps the file-path of posts/pages to the hash of their content.
That way, we can check each post/page before building by looking up their hash in the database file. (If there were no changes since the last build, we don't have to rebuild the file).
This way, we would only rebuild files that got changed, increasing build times massively.
We also don't need to introduce an actual database, maybe a simple json/xml/ini file is enough. Will have to see.

Summary:
We should provide the font file locally, to ensure that the correct font will be used, if it is not available by default.

Summary:

In the rust-rewrite of mublog, we want to be able to test pipeline operations, such as adding stages/features.
This can ensure that stages/features executed correctly and in order, and to also have tests that cover possible error paths.
This is probably a bit more involved than a a normal unit test, and might require a mocking-framework.

Summary:

While we can add heading, subheading and subsubheading in our posts, there is currently no table of contents.
I can see this being useful, especially when a post is fairly long, and consists of multiple different chapters.
However, such a feature should be optional, and the user should be able to decide if he wants a ToC or not via the config file.

There are multiple ways of implementing a ToC - one that I personally like a lot looks kinda like this:

The ToC should fullfill the following criteria:

• Scroll with the page, always stickied to the top
• Clicking on an element scrolls to the respective section
• Howevering over an entry should change the color
• The selected entry should be bold.

As for the configuration:

• The user should be have the option to disable a ToC if he does not like it.
• It might be sensible to set a default max indentation of 3

Notes:
We will also have to think about a good way to make this look decent on a mobile device (Or hide it, if there is no decent option).

Summary:

Currently, the script hard-crashes, if template files are missing.
We should handle that gracefully, log an error, and exit.

Summary:
We have a lot of files, in which we perform substitutions (such as the HTML header and footer), but also the tags js file etc.
Instead of having so many hardcoded strings, that get written as file, it might be sensible to have a template directory, that stores these templates, and the script just loads all the content from there.

Then we should also have some helper functions like replace_str(pattern, new_value), to prevent code duplication

Summary:

Every function should have type annotations. This improved intellisense during development, but it also makes the code more self-documenting. An example for type annotations is shown below.

Without type annotations:

def myfunc(a, b):

With type annotations:

def myfunc(a: int, b: str) -> str:

References:

• https://www.w3schools.com/python/python_datatypes.asp
• https://www.pythontutorial.net/python-basics/python-type-hints/

Summary:

One feature, that would be very useful, would be pagination for the post listings.
This is especially useful, when a blog-site has many posts.

Note: This will be implemented, once the Rust re-write has progressed further.

Summary:

The header validation function of the posts uses the Logger.log_fail() method twice in a row. First to print that header validation failed, and then to give some more information about what field in particular could not be validated.
However, since Logger.log_fail() causes the script to exit, the second print is never executed.

Suggestions:

The following changes could be done:

• Replace first log_fail() with a log_warn() instead
• Wrap both log_fail() calls in one. This requires a bit of adjustment to the formatting.

Summary
It would be nice to automatically generate an RSS feed.
A lot of people use RSS to read blogs, so it would be a good addition.

Notes:
We have to check how accurate time stamps need to be. Currently each post only has a date assign, but not time.
Unsure how this affects RSS polling, in terms of when a post is considered "new".

Summary:

It seems that the sorting of the article listing is broken.
Every article should be sorted by the date, with the latest one on top.

Summary

Currently the footer, that show's e.g. the copyright information of the blog, is not fixed to the bottom of the page.
It is only at the bottom, if the content of the page is long enough. Otherwise, it directly follows the page content, leaving large empty gap below, which doesn't look that great. Should be a simple fix.