search

emacs-love / weblorg

Static Site Generator for Emacs
https://emacs.love/weblorg
GNU General Public License v3.0
278 stars 20 forks source link

Weblorg Themes #20

Open guilhermecomum opened 3 years ago

guilhermecomum commented 3 years ago

melpa package with weblorg themes

nanzhong commented 3 years ago

Would this also require a shift in the way themes are managed by weblorg right now?

If I'm understanding correctly, currently the theme dir is always assumed to be in weblorg source path under themes . https://github.com/emacs-love/weblorg/blob/3c860c7b52ccee2f8d0b96e8a9e65e9695eb6e0a/weblorg.el#L696-L704

Seems like there would need to be a way to configure a different theme dir right?

clarete commented 3 years ago

Hi @nanzhong! thanks for taking the time to comment!

The function you linked is one of template sources, there are two right now: https://github.com/emacs-love/weblorg/blob/3c860c7b52ccee2f8d0b96e8a9e65e9695eb6e0a/weblorg.el#L258-L259 That first line is the templates directory of the website's project.

I'm still a bit uncertain about how to include this feature on top of the existing functionality. The main question is about how the theme would be selected by the user declaring routes. The first thing that comes to my mind is something like this:

(require 'weblorg)
(require 'weblorg-gruvbox) ; doesn't quite exist yet

(weblorg-site
  ;; This :theme prop currently takes a string, maybe the theme API should require the theme
  ;; have a function that returns its directory
  :theme (weblorg-gruvbox-theme-path)

  ;; maybe we keep :theme the way it is but take an additional parameter
  :theme-dir (weblorg-gruvbox-theme-path)
)

; ... everything else goes as usual

What do you think?

@guilhermecomum do you have any opinions here?

nanzhong commented 3 years ago

I like the idea you proposed about requiring themes to expose a function that returns its directory.

One gotcha I encountered with the 2 template sources right now (templates dir in base-dir or in the theme) is that weblorg-copy-static only seems to support the theme dir. I thought it also worked with the local templates and took a bit of digging before I realized this. I could also be misunderstanding something here, my grasp of elisp is very basic.

I wonder if it's worth considering removing support for the local templates dir entirely, and expect users to create a theme that lives together with the site. This would provide a consistent model for handling all the templating and static asset copying. This might also mean introducing some tooling to make it possible to "extend" a theme by providing overrides.

clarete commented 3 years ago

Hi @nanzhong, that's such great feedback! Thank you for taking the time to share it!

I kinda really liked your idea of having the website's root to have to contain an entire theme instead of just the template directory. I feel like that would also solve a bit of a weirdness I felt when copy-static was overriding stuff that I was working on all the time. The way I understood your idea, we'd end up with something like this:

blog/
├── posts/
│   └── ...
├── pages/
│   └── ...
├── themes/
│   ├── static/
│   │   └── ...
│   └── templates/
│       └── ...
└── publish.el

And back to the weblorg code, we'd have something like this instead:

 (template-dirs (list (weblorg--project-theme-dir base-dir) ; this new guy would expand to $base-dir/theme/templates
                      (weblorg--theme-dir theme "templates")))) ; this might have to get smarter to allow picking themes either shipped with weblorg or installed by an extension

Then copy-static would also have to be changed to copy from both static directories (the one from the theme and the one from the website's theme/static dir.

Do you think this would make things more consistent?

nanzhong commented 3 years ago

Yup! That's what I had in mind as well.

clarete commented 3 years ago

Alright, I did this change for moving the default template directory to site-root/theme/templates however, I kept the site-root/templates directory on the list for now just to not break things for people unexpectedly, but marked that option as deprecated and will plan for removing it in 0.1.3 (two releases from now).

The next step here is to work out the change for allowing external theme directories. Gotta make a decision on a clean API for allowing users to pick themes that are shipped within the weblorg as well as themes shipped in separate packages. One step at a time!! 🩰

clarete commented 3 years ago

Oh, and of course, here's the actual change: https://github.com/emacs-love/weblorg/commit/d4ca82395bcafc7dff070290b0e8241204188da2 :)

clarete commented 3 years ago

Just stopping by to share some good news. As I reported in ticket #23, I recently pushed a change to weblorg that reconciles all this PATH related information in a consistent way. The theme directory within the root of the website's source is now fully supported for both themes and templates!

Here's the change: https://github.com/emacs-love/weblorg/commit/e2ae9b14f9ad736f52a7b4275076bc24a45926f8. And here's the documentation for it: https://emacs.love/weblorg/doc/file-paths.html

We're now ready to actually leverage external themes so this issue is currently unblocked!