open-ephys / bonsai-onix1-docs

Documentation for the OpenEphys.Onix1 Bonsai package
https://open-ephys.github.io/bonsai-onix1-docs/
Creative Commons Attribution Share Alike 4.0 International
0 stars 2 forks source link

Add a way in the template to center images? #49

Closed bparks13 closed 2 months ago

bparks13 commented 3 months ago

Is there any way to modify the template or to add some CSS that will center images? Using the default format of ![Title](../link/to/image.png) attempts to stretch the image from end to end, which makes it appear centered, but if we want to set a particular width (i.e. ,![Title](../link/to/image.png){width=600px}) then it will always be a left-aligned image.

It is possible cheat a little bit and directly inject HTML into the markdown file, but this goes against the philosophy of Markdown. Adding HTML like this works

<p align="center">
  <img src="../link/to/image.png">
</p>

But this doesn't look very clean in the Markdown file, and also might not be properly rendered depending on what is serving the page.

My preferred method would be to add an align="center" parameter after the pixel width if possible (i.e., ![Title](../link/to/image.png){width=600px,align="center"}), I think this keeps it as clean as possible while allowing for some customizability. However, I genuinely do not know if this is possible on the backend, hence the Question label.

cjsha commented 3 months ago

To answer your question, yes. We can do something like I did for #44. But should we?

I like Markdown because it's super legible in its raw format while editing, but I'm also finding it super limited in flexibility when it comes to formatting the website. For example, we need custom make custom containers to make captioned images (again, #44). We also can't, for example, put text and an image side-by-side in standard Markdown afaik. I'm kinda feeling like we just should just start using HTML whenever we want more out of our .md files. The containers add a layer of (unnecessary imo) abstraction. And I'm not sure we should be creating create custom containers for every little bit of custom HTML we want.

I'm not sure what benefit there is to keep our markdown compatible with some base-flavor easily-readable markdown ideal. These .md files are meant to be processed by docfx, not for anything more general than that. As long as docfx processes HTML ok (it does), and the HTML passes linkchecks ok (I'm pretty sure it will unless you're doing some funky stuff like I was a few weeks ago), I feel like we should just use HTML instead of custom containers.

This is not a real suggestion in any way, but I'm starting to feel like It'd prefer to work in pure HTML. Restructured text, Markdown, etc. all get converted to html anyway. I think the problem is its readability, but HTML is still a markdown language, it's not that difficult to read. It's not like we're going from c to assembly here.

cjsha commented 2 months ago

With that said, I know jonnew's big on left-alignment. I don't really mind much either way

jonnew commented 2 months ago

@bparks13 Addressed this in #52. We can see if that resolves this issue.