Support for pymdown-extensions

[benjaoming]

The default of django-wiki should be to depend on pymdown-extensions and have out-of-the-box CSS support for a set of plugins.

https://facelessuser.github.io/pymdown-extensions/

[orcephrye]

I would also love to see this. But there are a lot of extensions, and some of them seem like a challenge to add.

For example: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/

How would one go about implementing that? Add custom MDs to a static directory? How would that be managed? Or perhaps have a wrapper around the extension to pull down raw MD from a slug?

[benjaoming]

@orcephrye Agreed! I think that snippets cannot be supported, especially since it says "Not Meant for User Facing Sites" in its docs ❗

Actually, the support of the extensions should probably be added 1-by-1. So if someone wants to add support, they could focus on adding it for just the extension that they need.

The philosophy of django-wiki is also to leverage Django models to store and organize knowledge/data. It's like what Wagtail went and did, too. This might mean that support would have to be customized for the extensions. An example would be: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ - adding and managing task lists is something I would find significantly more useful if it was stored in a model.

[orcephrye]

Agreed I thought about using a model somehow for both tasklist and tables. Not all tables but some may be better suited if the date wasn't in a md file. I have some very big tables. 10s to thousands ofrows with dozens of columns. It becomes extremely unwieldy to put that in MD especially if you want/need custom css.

Well maybe I will look at implementation of one of the extensions. Any suggestions for a first easy one?

[benjaoming]

Well maybe I will look at implementation of one of the extensions. Any suggestions for a first easy one?

I can try to share how I would do this -- but only since you ask :) This will sound a lot like all talk, no action from my side :) So this is just a suggestion... it's my first take on how to approach it:

If you start by introducing the simplest form of extension, I would think it's easier to focus on merely getting a nice structure for the plugins. This rules out the sort of extensions that contains structural data (the kind we want to store in a Django model).

I think that it could make sense to create a top-level package called wiki.plugins.pymdown (for common stuff) and have wiki.plugins.pymdown.<extension_name> for each extension so individual extensions are enabled through INSTALLED_APPS.

I think that the blocks.* extensions look extremely useful. They don't contain any data structures that are useful in a database (sure, we could mirror tabs in the database.. but seems useless).

• https://facelessuser.github.io/pymdown-extensions/extensions/blocks/

There's also a stand-alone tabbed extension, but I would think it's fine to choose the one in the blocks collection?

• https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/

And then there's superfences where (not sure) it seems like it might be both very useful and perhaps not require any static assets:

• https://facelessuser.github.io/pymdown-extensions/extensions/superfences/

Based on having the first extension without any data models ready, it would seem easier to focus on for instance tasklist.

These ones also look useful in a wiki:

• https://facelessuser.github.io/pymdown-extensions/extensions/details/
• https://facelessuser.github.io/pymdown-extensions/extensions/mark/
• https://facelessuser.github.io/pymdown-extensions/extensions/extra/ (seems like it needs to be implemented at some point, but in itself it doesn't any value)

[oscarmcm]

Wouldn't be good first to update Markdown to the latest version?

[benjaoming]

Good point!

[orcephrye]

@oscarmcm
I did a thing: #1312
It links to the work I have currently done: https://github.com/orcephrye/django-wiki/tree/python_markdown_34_support

[orcephrye]

Not sure if this should be closed just yet.

1. I still have questions and feel that Python markdown 34 support #1313 was merged early.
2. This issue is about more than just the Blocks extension for Pymdown. But the merge only added support for blocks and not even all the block extensions.

[oscarmcm]

Ahh okey, I got it.

Gonna reopen it, so we can add support for the rest of the plugins too.

[oscarmcm]

We might need a way to reconcile the work being made in

• Python markdown 34 support #1313
• Pymdown blocks support #1316

Do you feel that those PR are stable? If there's more work need in order to fulfill this issue, we can work on a new PR.

There's no point on having big long diff PR's - If we can work at macro level, that would be awesome.

I might need to check more deep pymdown-extensions

[orcephrye]

I normally squash my comments down to just a few or just one. So sorry for some of the confusion. Also, I thought the best option would be to fork the project and work from my own repo but now I believe that all that has done is add extra syncs into my PRs that make things confusing.

So sorry about some of this mess I didn't mean to be more confusing.

I do not like big long diff PRs either. I wanted to add Block and only Block support from PyMdown into the wiki and then work extension by extension after that.

The #1313 should be stable I do not see why it wouldn't be. It was a big change under the hood but all the tests including selenium came back good.

The #1316 should be fine as well. It is doing very little. Just setting up PyMdown blocks as additional extensions to load and adding more things to the bleach whitelist.

I wasn't concerned about stability. I was concerned about the look and feel among other things. Here are my questions:

1. Does the color fit?
2. Should Icons for the different types be a good idea?
3. Should we add documentation in the Markdown editor as we do for the Macros plugin?

Thanks again for your time.

[orcephrye]

Also as an aside. I am totally for a follow-up merge request to address my questions. I do not think we need to undo previous changes.

[benjaoming]

@orcephrye that sounds great! So for now, it's a plugin that isn't enabled by default and will receive some more work to be ready.

I would say "YES" to all three of your suggestions for improvements.

[orcephrye]

Ok so I wanna try to tackle each question one at a time with a PR for each.
First question. "Does the color fit?" So here are some screenshots of what I am working with at the moment.

Below is what Details looks like with no type. Using the primary/secondary color schema IE: primary/secondary/success/info/warning/danger. As you can see it is all the same. However, if I change the type to be alert-X (ie alert-[primary|secondary|etc...] It works!

Here is Admonition. I put a little more effort into getting custom colors for its supported types.

Here when using the supported list of colors I define in scss/_admonition.scss (Which I cleaned up a little ) They look nice...?? But they do not fit the color schema provided by the Wiki which is sorta lame. I mean it would be nice if those were extra colors that could be used like 'alt-warning' or something like that. Also, I would like to add those colors to the details once we figure that out.

The main issue I am having is that Details doesn't seem to be able to use the primary/secondary/etc... colors provided by the wiki. I can add them into the scss/_details.scss file but how? How do I get those colors? Where are they defined? I see a lot of stuff in scss/_variables.scss but not those. So I am a little lost.

Also, does that even look good!? I am NOT a CSS or UI expert. Any help/guidance would be welcome. Thanks!

[benjaoming]

Ok so I wanna try to tackle each question one at a time with a PR for each.
First question. "Does the color fit?" So here are some screenshots of what I am working with at the moment.

Writing stylesheets is a lot like programming: Use variables for values that someone could wish to configure.

In this case, try to re-use the variables from our Bootstrap-based theme by using these:

django-wiki/src/wiki/static/wiki/bootstrap/scss/_variables.scss

Lines 67 to 74 in d416db3

	$primary: $blue !default;
	$secondary: $gray-600 !default;
	$success: $green !default;
	$info: $cyan !default;
	$warning: $yellow !default;
	$danger: $red !default;
	$light: $gray-100 !default;
	$dark: $gray-800 !default;

You may use built-in functions lighten and darken to alter the colors while sticking to their original composition.

[benjaoming]

Because of a bad and not so self-explanatory structure, custom SCSS that isn't included in original Bootstrap source file should go in this folder: https://github.com/django-wiki/django-wiki/blob/main/src/wiki/static/wiki/bootstrap/scss/wiki/

[orcephrye]

Because of a bad and not so self-explanatory structure, custom SCSS that isn't included in original Bootstrap source file should go in this folder: https://github.com/django-wiki/django-wiki/blob/main/src/wiki/static/wiki/bootstrap/scss/wiki/

Does that mean files like scss/_details.scss need to be moved?

[orcephrye]

I have made these changes to the details.

Notice how the ones at the bottom are the same colors but sorta muted? I cannot find out where that is happening. I know at one point I stumbled upon it. But not sure. In either case, is that what you would expect?

Also, the style has it so that the border stays the same but the summary changes to a white background while the details keep the background of the type. IE:

Does that look good? It is a little hard to make out the border because they are all next to each other.

[benjaoming]

@orcephrye thanks for sharing details from your work! I get the idea that perhaps using the SCSS function @extend could work.

Something like:

summary {
    @extend .alert-secondary;
}

I could be wrong about some assumptions here. But try to search the source files for other examples of its usage.

https://www.w3schools.com/sass/sass_extend.php

On another note, we should target CSS rules as exact as possible. Something like:

.wiki-article summary {
    @extend .alert-secondary;
}

[orcephrye]

@orcephrye thanks for sharing details from your work! I get the idea that perhaps using the SCSS function @extend could work.

Actually, I found this:

django-wiki/src/wiki/static/wiki/bootstrap/scss/_alert.scss

Line 50 in d416db3

@include alert-variant(theme-color-level($color, $alert-bg-level), theme-color-level($color, $alert-border-level), theme-color-level($color, $alert-color-level));

So I am using the 'theme-color-level' in order to follow the same thing. And it works great! The only question now is should I be following the exact color levels or maybe something a little different for Details/Summary? So the alert levels are found here: scss/_variables.scss

I could make a few new variables and change up the levels a tiny bit. But I am also good at keeping it like it is.

What I currently have done: orcephrye@552ec34

I just want to be extra careful before making another PR. And the next PR I make will be a draft to start off with.

[orcephrye]

Well, thanks to the holidays I have gotten some free time and started working on how to show Font Awesome Icons for Alerts/Admonitions/Details.

The easiest solution is already provided. Simply add the class via the 'attrs' option that is supported by Blocks via PyMdown Extensions. IE:

/// admonition | Typeless Summary
    attrs: {class: fa-solid fa-user}

Typeless Content...
///

This generates the element:

<div class="admonition fa-solid fa-user">
<p class="admonition-title">Typeless Summary</p>
<p>Typeless Content...</p>
</div>

But that does seem to work. I simply get an 'X' box. It is as if Font Awesome is not installed or being pulled correctly.

The other option is to add it via SCSS. Which I do not prefer. The reason is it feels too static. If a person wishes to add an icon they can do so through 'attrs'.

Either case it doesn't at all work. I am not sure if I am missing something obvious here. A little help would be nice.

[orcephrye]

I have added what I hope to be my final update for PyMDown support for the time being. This completes the plugin by adding documentation that should appear as a sidebar in the markdown editor. Sorry for the delay in getting this out. I hoped to have this complete by December of last year and stuff just got in the way. Tis life.

#1334