switching

[hug-sch]

Hi,
I sent the following email to [email protected] (address from frontpage. Is it still correct?)

I discovered your “caption” github repo today. Are you still maintaining it?
At the moment I’m using MkDocs Caption: https://pypi.org/project/mkdocs-caption/ but I would be gladly to use your tool. It seems easier to use and is more in line with standard markdown.
The reason I picked MkDocs Caption is that it’s possible to add a class to the Figure tag, so that it can be styled, for example to right align.
I’m not very good at CSS nor HTML, so may be it can be done otherwise (see the PP Help portfolio-help/overrides/assets/stylesheets/extra.css at master · portfolio-performance/portfolio-help (github.com) for how I've tried to do it.
Hugo

[flywire]

Thanks for pointing out that email, those emails are redirected and I missed them in the original spam folder.

Long story short is I haven't maintained this repo for a long time, see point 5 below.

History:

1. Original concept: https://stackoverflow.com/questions/62442344/how-to-automatically-number-mkdocs-figures-sequentially
2. First implementation of plugin effectively using a markdown syntax extension but designed so it still looks reasonable if a document is generated without the plugin: https://git.sr.ht/~ferruck/yafg
3. My fork https://github.com/flywire/caption - my vision was to use OOP (polymorphism ??) so the same plugin would work for the three caption types but my coding skills are not good enough
4. I couldn't get effective support to resolve my coding issue or find another project sponsor
5. @sanzoghenzo sanzoghenzo offered to get it working for the three caption types but just split it into three plugins. I'd been rolling his commits into master and they broke the plugin. It needs some git work to unroll the changes.
6. You alerted me to https://github.com/tobiasah/mkdocs-caption which included some unique concepts and syntax I developed, and there was no comment on the source of those ideas, so I raised Consider Caption Project tobiasah/mkdocs-caption#7. It handles the three caption types, the coding is better than mine.

I'd like to see @tobiasah respond the issue with a view to consolidating the projects.

I'll take up the issues with your project elsewhere.

[tobiasah]

Sorry for being silent for so long on the issue you raised. It's on my to-do list, but I have not had the time to look into your project and the concepts you came up with before me.

I was not aware of your plugin when I was developing mine. Interestingly enough, we have both taken a similar approach regarding the markdown syntax. I am happy to add a reference to my project and credit you for the syntax.

I developed my plugin specifically for mk-docs and used their hooks. Since I use the mkdocs-material theme, I tried to integrate it best into it. Coming for Antroa I was missing figure and table captions quite dearly and could not find a mkdocs plugin that does the trick.

@flywire If you want to collaborate and bring the two projects closer together, I am more than happy to do so.

[sanzoghenzo]

Wait, what is that is not working after my PRs? You merged it and never gave any feedback. Tests are passing, if you need more thorough tests, please say so.

Also, you didn't push a single line of code in 4 years, what has @tobiasah to gain to "consider" your (broken, as you said) project?

[flywire]

@tobiasah Wow, interestingly most of that syntax is identical to the character. I've been using mkdocs-material too but I don't know anything about AsciiDoc.

Given the similarity in syntax I think it would be pretty trivial for users to switch from caption to mkdocs-caption. (It would be known after running a few test files.) My recollection there are differences in some of the more involved features and what was implemented/proposed in caption would be worth considering. Most of the caption analysis is summarised in the docs and issues, including CSS examples.

I'd be keen to work through this as part of a collaboration with a view to retiring caption.

@sanzoghenzo I understand you can't know how much effort I put into this project. Coding is a hobby for me and despite trying to learn more OOP and seeking support from others it is not a solution to my satisfaction.

I consider the project currently fails, despite all efforts including your own, on the basis of no longer running the tests or a single plugin formatting all caption types link.

[sanzoghenzo]

(Sorry @hug-sch for totally hijacking your issue... by the way, what exactly are you asking here? Just to add custom classes to figures?)

@flywire I can sympathize with your struggles with OOP, even I had a hard time understanding it back at school!

My comment about the 4 years without new lines of code was not meant to offend you, but simply to rest my case: what does your project offer more than mkdocs-caption? This is not counting your wishes/vision of the code (that didn't materialize in 4 years, hence my comment) but analyzing the current, concrete code ("mine" is broken, "yours" was a bit of a coding mess).
(Here @hug-sch can help: what do you find "easier" with caption than with mkdocs-caption?)

If really there are features that can be bridged to, why ask @tobiasah to "consider" your code instead of making a PR to include the improvements to its project?

I get that you're a hobbyist, but the day you publicly opened this repo, and most importantly published the package to pypi, you put yourself in the position of being an open source project maintainer.
As such, you should be able to manage PRs, review the code and ask for specific improvements.
Doing nothing (publicly) and hoping that others do the work for you is not the way open source works.
If it's broken, fix it. If you can't fix it, roll it back. If you can't afforthe maintenance, remove the package from pypi and close the repo. It's that simple.

I must admit I didn't put much effort in the generic listing plugin since I had no use for it, but as I already wrote, a kind request to test against the example you linked could have been enough to nudge me and move things forward.

Also, there are two, 1 year-old PRs waiting for your actions. One of them fixes one of the errors in the generic listing plugin...

[hug-sch]

@sanzoghenzo Hi, sometimes I need to insert a figure with its numbered caption that is right-aligned to the webpage. With mkdocs-caption, one can assign a class to the Figure tag. With my limited knowledge of CSS and HTML, that seemed the only way how I could achieve that from within the markdown. The disadvantage, however, is a little more complex syntax. In mkdocs-caption, one has to write:

Figure: Example of Deposit Accounts. {class="pp-figure"}

![](../images/myImage.png)

and remember that there must be a blank line between Figure and ![] The CSS of the class pp-figure then handles the alignment.

[tobiasah]

@tobiasah Wow, interestingly most of that syntax is identical to the character. I've been using mkdocs-material too but I don't know anything about AsciiDoc.

Given the similarity in syntax I think it would be pretty trivial for users to switch from caption to mkdocs-caption. (It would be known after running a few test files.) My recollection there are differences in some of the more involved features and what was implemented/proposed in caption would be worth considering. Most of the caption analysis is summarised in the docs and issues, including CSS examples.

I'd be keen to work through this as part of a collaboration with a view to retiring caption.

@sanzoghenzo I understand you can't know how much effort I put into this project. Coding is a hobby for me and despite trying to learn more OOP and seeking support from others it is not a solution to my satisfaction.

I consider the project currently fails, despite all efforts including your own, on the basis of no longer running the tests or a single plugin formatting all caption types link.

So, if I understand correctly, your idea would be to get some kind of feature parity in mkdocs-caption and make it a successor of your project? If yes, I think it would be good to gather all the things that are currently missing or should be improved here tobiasah/mkdocs-caption#7. Then, I can implement them one after another. How does this sound to you?

The only concern I have is that your project is a native Markdown plugin, and mkdocs-caption is tailored to mkdocs and does not work without it ... So switching does only work if one uses mkdocs ...

@hug-sch If you have a better idea or a wish for an improvement on how inject HTML syntax into the captions feel free to create a issue so we can find the best solution https://github.com/tobiasah/mkdocs-caption.

My thoughts on this are:

• The curly brackets are the native markdown way to add HTML properties, so it was the natural syntax for me.
• The empty line is required since one can write multiline captions, which would otherwise be hard to detect ... Markdown itself requires this empty line to differentiate separate blocks ...

[flywire]

So, if I understand correctly, your idea would be to get some kind of feature parity in mkdocs-caption and make it a successor of your project? If yes, I think it would be good to gather all the things that are currently missing or should be improved here tobiasah/mkdocs-caption#7. Then, I can implement them one after another. How does this sound to you?

Yes, good.

The only concern I have is that your project is a native Markdown plugin, and mkdocs-caption is tailored to mkdocs and does not work without it ... So switching does only work if one uses mkdocs ...

Worst case this project will remain with a tidy up for native Markdown.