doc/plugins/contrib/bootstrap.mdwn

   1 [[!meta author="anarcat"]]
   2 [[!template id=plugin name=bootstrap author="[[anarcat]]"]]
   3 [[!tag type/chrome]]
   4 [[!template  id=gitbranch branch=anarcat/bootstrap-plugin author="[[anarcat]]"]]
   5
   6 ## Rationale
   7
   8 One of the most annoying features of bootstrap and/or the (informal)
   9 [[bootstrap theme|todo/merge_bootstrap_branch/]] is the lack of styling on tables. It makes
  10 tables look horrible! Look, for example, as the table in [this
  11 page](https://web.archive.org/web/20180513200625/https://anarc.at/blog/2018-04-12-terminal-emulators-1/): margins are tiny so everything is jumbled up together, and
  12 there are very little visual markers to differenciate between cells. I
  13 don't have a better example handy, but this is particularly bad when a
  14 cell ends up having long lines of text that are wrapped with multiple
  15 lines.
  16
  17 Bootstrap has a nice [table](https://getbootstrap.com/docs/4.0/content/tables/) style that is not automatically
  18 applied to all tables, probably to avoid breaking table-based layout
  19 and other custom controls like calendars a random site might spew
  20 out. Unfortunately, the various Ikiwiki output plugins (most notably
  21 the [[plugins/mdwn]] plugin) do not add that class to generated
  22 tables.
  23
  24 ## Solution
  25
  26 I found there are two ways of fixing that. One is to use raw HTML: the
  27 [[plugins/htmlscrubber]] plugin will let through `class` elements in
  28 tables so this will actually work:
  29
  30     <table class="table"><tr><td>This<td>is<tr>a<tr>table!</table>
  31
  32 But of course, it would be nice if Markdown-formatted tables would
  33 actually render correctly as well. For this, I have written a [simple
  34 plugin](https://gitlab.com/anarcat/ikiwiki/blob/bootstrap/IkiWiki/Plugin/bootstrap.pm) that adds that class to empty table tags. It's very dumb, but
  35 it should generally work, or at least it works for my case. It will
  36 not touch any `<table>` tag that already has other class elements, so
  37 it should be safe to use alongside other plugins that generate their
  38 own `<table>` markup, provided they *do* add some sort of `class`,
  39 `id` or other attribute. Unfortunately, the [[plugins/contrib/bibtex]]
  40 plugin does not do that correctly and somewhat looks ugly with this
  41 plugin. Compare for example, [this old version](https://web.archive.org/web/20170717065911/https://anarc.at/communication/) with [the new
  42 rendering](https://web.archive.org/web/20180626203321/https://anarc.at/communication/). I'm still unsure which one looks better, actually...
  43
  44 ## Discussion
  45
  46 Anyways, I wasn't quite sure where to put this, but it seems like an
  47 important improvement to make if we're going to
  48 [[todo/merge_bootstrap_branch]]. I am not sure of the implementation
  49 at all: the best way I found to edit only the rendered content (and
  50 not the whole HTML page with the template) is to use the `sanitize`
  51 hook, but I'm not sure it's the right way to go. It certainly seems
  52 backwards to introduce new markup in a "sanitization"
  53 procedure. Furthermore, I first tried to change *all* `<table>` tags
  54 even if they had extra attributes, but I found I didn't want to add
  55 `class` attributes to elements that already had some, soand that ended
  56 up making the regex work way too messy, so I stuck to the simpler
  57 way.
  58
  59 Furthermore, there might be other markup elements we want to improve
  60 upon. This only fixes tables, but maybe other elements would benefit
  61 from additionnal styling. The [content](https://getbootstrap.com/docs/4.0/content/reboot/) section of the bootstrap
  62 docs says there are special classes for tags like `img`, `form`,
  63 `input` and `div` that might be interesting to look at...
  64
  65 -- [[anarcat]]