Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FEATURE] Per-directory settings. #17

Closed
Andre601 opened this issue Feb 11, 2022 · 8 comments
Closed

[FEATURE] Per-directory settings. #17

Andre601 opened this issue Feb 11, 2022 · 8 comments
Labels
enhancement New feature or request help wanted Extra attention is needed

Comments

@Andre601
Copy link
Contributor

Idea

It would be cool if the blogging plugin would allow defining certain settings on a per-directory level such as a category (More on that in a bit).

It would allow a much higher amount of customization that the plugin is already offering.

Categories

I mentioned categories. By that I mean a way to "group" certain blog directories together to then display.

Some bloggers may have different categories/blogs for different purposes.
As an example could I have a posts category for casual blog posts and a reviews category where I only have reviews.

Example configuration:

plugins:
  - blogging:
      dirs:
        # Combines all posts from "blog/posts/" into a category called "posts"
        - category: posts
          dirs:
            - blog/posts
        # Combines all posts from "blog/reviews/" into a category called "reviews"
        - category: reviews
          dirs:
            - blog/reviews

You would then be able to use the category name in the {{ blog_content }} placeholder to only list pages from the dirs of that group.
Example: {{ blog_content reviews }}

Other options

If this setup would be implemented would it be cool if the options of it could be included for those directories too.

Example:

plugins:
  - blogging:
      dirs:
        # Uses the default settings listed below
        - category: posts
          dirs:
            - blog/posts
        # Would override size and template but otherwise uses global settings
        - category: reviews
          size: 5
          template: overrides/blog/review-template.html
          dirs:
            - blog/reviews
      size: 10
      template: overrides/blog/blog-template.html
      features:
        tags:
          index_page: blog/tags.md

How is that useful

It would allow us to have high control of how and where we would serve specific content (blog posts) without the trouble of having to stick with one single blog section.

I'm aware that this is a huge task, if not even impossible with how the plugin may be structured right now and I feel sorry that I can't contribute any code to it to help with. But I hope it's doable and that it is considered.

@liang2kl
Copy link
Owner

I have considered this before, but for some reason I might not be able to implement this at this moment (maybe some time later I will look into this).

  • it will be a huge task, as you mentioned
  • it takes a significantly different architecture design
  • it will introduce much more complexity, which may not be suitable for a tiny plugin

Actually I have found the plugin limited myself, because MkDocs does not provide the exact APIs needed to build a blogging plugin. Thus, some current implementation is ugly, and the addition of features is hard to achieve. Because of that, I switched to Hugo a few weeks ago (and abandoned my own plugin, but I will keep maintaining). You can try out some dedicated blog site generators if you need advanced blogging features.

@liang2kl liang2kl added enhancement New feature or request help wanted Extra attention is needed labels Feb 12, 2022
@liang2kl liang2kl pinned this issue Feb 12, 2022
@Andre601
Copy link
Contributor Author

Andre601 commented Feb 12, 2022

I see... Sad to hear about this unfortunate status, but I guess it happens.

One idea could perhaps be to use frontmatter to override settings on a per-page level.
It could reduce work on the code end I would assume at the cost of adding frontmatter to multiple pages.

@liang2kl
Copy link
Owner

liang2kl commented May 1, 2022

I managed to implement a version based on your idea. It's currently on the branch feat/categories, and (because I don't write any tests) it needs some tests from users.

The new docs: https://github.com/liang2kl/mkdocs-blogging-plugin/blob/feat/categories/docs/index.md. In short, you can setup categories in this way:

plugins:
  - blogging:
      # --- GLOBAL-CATEGORY: configs for {{ blog_content }} ---
      dirs:
        - blog
      template: override/custom-blog.html
      # --- END GLOBAL CATEGORY ---

      # --- INDIVIDUAL CATEGORIES: configs for {{ blog_content name }} ---
      categories:
        - name: reviews
          dirs:
            - reviews
      # --- END INDIVIDUAL CATEGORIES ---
   
      # Other globally applied options
      ...

To install:

pip install git+https://github.com/liang2kl/mkdocs-blogging-plugin@feat/categories

I will appreciated it if you would help testing this ^_^

@liang2kl
Copy link
Owner

liang2kl commented May 2, 2022

Now it's available as version 2.0.0

@liang2kl liang2kl closed this as completed May 2, 2022
@liang2kl liang2kl unpinned this issue May 2, 2022
@Andre601
Copy link
Contributor Author

Andre601 commented May 2, 2022

Hey.

Sorry for not replying but not only was GitHub for some reason not sending me an e-mail about the notif, but I also was a bit busy recently...

I tried out 2.0.0 and received the following error during Build using Netlify [Full Log]

2:13:15 PM: $ mkdocs build
2:13:15 PM: Traceback (most recent call last):
2:13:15 PM:   File "/opt/buildhome/python3.7/bin/mkdocs", line 8, in <module>
2:13:15 PM:     sys.exit(cli())
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1130, in __call__
2:13:15 PM:     return self.main(*args, **kwargs)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1055, in main
2:13:15 PM:     rv = self.invoke(ctx)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1657, in invoke
2:13:15 PM:     return _process_result(sub_ctx.command.invoke(sub_ctx))
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 1404, in invoke
2:13:15 PM:     return ctx.invoke(self.callback, **ctx.params)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/click/core.py", line 760, in invoke
2:13:15 PM:     return __callback(*args, **kwargs)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/__main__.py", line 192, in build_command
2:13:15 PM:     build.build(config.load_config(**kwargs), dirty=not clean)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/base.py", line 224, in load_config
2:13:15 PM:     errors, warnings = cfg.validate()
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/base.py", line 108, in validate
2:13:15 PM:     run_failed, run_warnings = self._validate()
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/base.py", line 63, in _validate
2:13:15 PM:     self[key] = config_option.validate(value)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 130, in validate
2:13:15 PM:     return self.run_validation(value)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 679, in run_validation
2:13:15 PM:     plgins[item] = self.load_plugin(item, cfg)
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 692, in load_plugin
2:13:15 PM:     Plugin = self.installed_plugins[name].load()
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/importlib_metadata/__init__.py", line 203, in load
2:13:15 PM:     module = import_module(match.group('module'))
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/importlib/__init__.py", line 127, in import_module
2:13:15 PM:     return _bootstrap._gcd_import(name[level:], package, level)
2:13:15 PM:   File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
2:13:15 PM:   File "<frozen importlib._bootstrap>", line 983, in _find_and_load
2:13:15 PM:   File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
2:13:15 PM:   File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
2:13:15 PM:   File "<frozen importlib._bootstrap_external>", line 728, in exec_module
2:13:15 PM:   File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_blogging_plugin/plugin.py", line 51, in <module>
2:13:15 PM:     class BloggingPlugin(BasePlugin):
2:13:17 PM: Creating deploy upload records
2:13:15 PM:   File "/opt/buildhome/python3.7/lib/python3.7/site-packages/mkdocs_blogging_plugin/plugin.py", line 76, in BloggingPlugin
2:13:15 PM:     categories: dict[str, BloggingConfig] = {}
2:13:15 PM: TypeError: 'type' object is not subscriptable

Plugin Configuration as of right now:

  - blogging:
      dirs:
        - posts/2020
        - posts/2021
      features:
        tags:
          index_page: 'posts/tags.md'
          insert: top
      template: 'theme/blog/blog-override.html'
      theme:
        name: card
      locale: de
      size: 5
      time_format: '%d.%m.%Y'
      meta_time_format: '%d.%m.%Y'

@liang2kl
Copy link
Owner

liang2kl commented May 2, 2022

Thank you for the feedback.
It seems that the python version required for something like dict[str, BloggingConfig] is 3.9+. I'm having a fix now.

@liang2kl
Copy link
Owner

liang2kl commented May 2, 2022

Version 2.0.1 should be able to run under python3.7 now.

@Andre601
Copy link
Contributor Author

Andre601 commented May 2, 2022

Thanks, that fixed it.

I would've liked to try and use Python 3.9, but for whatever reason is Netlify only supporting 3.7 as newest version :/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

2 participants