I could call Bascule complete. It generates this website quickly and smoothly; it handles images well enough; it's extensible in a way I've never managed before. But I'm not very satisfied with it, and one of my biggest problems is that the code is a bit of a mess. When I open up the code to make some change or tweak, I am never sure exactly where to begin. Which class is responsible for which operation? Why is the code littered with TODO statements? Is it extensible in the right ways? Does it pull in too many dependencies for what it does?

Bascule has to regenerate every page every time; other generators can be more selective. Can I improve this performance, and still provide the navigation generation and listing pages which other generators tend not to provide?

I'd like to do a refactoring sweep of the code and try to bring it to order, though I am worried that I'll break more than I'll fix.

Markdown limitations

I've also been fighting with Markdown, the text formatting language used in Bascule (and widely across the web). It's very flexible, and a few additional plugins have made it very useful. For instance, using the flexmark attributes extension, I can apply CSS styling to my markdown:

  {.has-border}![bascule bridge](/assets/inchinnan-bascule-bridge.jpg "Inchinnan Bascule Bridge, Renfrew, Scotland"){.is-pulled-left .image }[Inchinnan Bascule Bridge](https://sirwilliamarrol.wordpress.com/2016/10/20/raising-of-inchinnan-bascule-bridge/) {.caption}

And with the tables extension I can layout nice simple tables:

	|Table heading 1|Table heading 2|
	|---|---|
	|Row 1, Col 1|Row 1, Col 2|
	|Row 2, Col 1|Row 2, Col 2|
Table heading 1Table heading 2
Row 1, Col 1Row 1, Col 2
Row 2, Col 1Row 2, Col 2

And I can combine them for a little additional styling:

	|Table heading 1|Table heading 2|
	|---|---|
	|Row 1, Col 1|Row 1, Col 2|
	|Row 2, Col 1|Row 2, Col 2|
	|Row 3, Col 1||
	{.table .is-bordered .is-striped .is-fullwidth}
Table heading 1Table heading 2
Row 1, Col 1Row 1, Col 2
Row 2, Col 1Row 2, Col 2
Row 3, Col 1

But I quickly hit limits. For instance, it is not possible to target a single row of a table. Here's the result I would like, applying the is-selected class to the second row:

<table class="table is-bordered is-striped is-fullwidth">
  <thead>
    <tr><th>Table heading 1</th><th>Table heading 2</th></tr>
  </thead>
  <tbody>
    <tr><td>Row 1, Col 1</td><td>Row 1, Col 2</td></tr>
    <tr class="is-selected"><td>Row 2, Col 1</td><td>Row 2, Col 2</td></tr>
    <tr><td colspan="2">Row 3, Col 1</td></tr>
  </tbody>
</table>

Which should appear as:

Table heading 1Table heading 2
Row 1, Col 1Row 1, Col 2
Row 2, Col 1Row 2, Col 2
Row 3, Col 1

But there is no way to target the second row using flexmark attributes:

|Table heading 1|Table heading 2|
|---|---|
|Row 1, Col 1|Row 1, Col 2|
{.is-selected}|Row 2, Col 1|Row 2, Col 2|
|Row 3, Col 1||
{.table .is-bordered .is-striped .is-fullwidth}

Rather unhelpfully returns:

Table heading 1Table heading 2
Row 1, Col 1Row 1, Col 2
Row 2, Col 1Row 2, Col 2
Row 3, Col 1

A similar result appears if I move {.is-selected} to the end of the row. It is at least possible to target a particular table column (a <td...> element in the HTML) so I could chain these together to create a similar effect:

|Table heading 1|Table heading 2|
|---|---|
|Row 1, Col 1|Row 1, Col 2|
|{.is-selected}Row 2, Col 1|{.is-selected}Row 2, Col 2|
|Row 3, Col 1||
{.table .is-bordered .is-striped .is-fullwidth}
Table heading 1Table heading 2
Row 1, Col 1Row 1, Col 2
Row 2, Col 1Row 2, Col 2
Row 3, Col 1

But that is not quite semantically correct and requires some very noisy markdown text.

Creating block-level elements

Markdown, in particular flexmark, assumes that every block should be rendered as an HTML paragraph, unless explicitly designed otherwise. So the following markdown source wraps my image tag in an unnecessary <p> tag:

![bascule bridge](/assets/inchinnan-bascule-bridge.jpg "Inchinnan Bascule Bridge, Renfrew, Scotland")

Becomes:

<p><img src="/assets/inchinnan-bascule-bridge.jpg" title="Inchinnan Bascule Bridge, Renfrew, Scotland"></p>

Try as I might, I can't find a way of suppressing this <p> tag.

More than this, I'd really like a way of creating HTML <div> elements within the markdown code, without resorting to writing, well, HTML. Markdown doesn't handle this well. While there are some proposed solutions, there doesn't seem to be an agreed solution in the markdown community. With the drive to increased semantic markup in HTML5, it is a pity that markdown does not provide a way of creating <section>, <article>, <details> or <aside> block-level elements.

Perhaps I'm asking too much. Markdown is not supposed to be a complete replacement for HTML, and there will always be limitations. I'd like to explore writing my own extensions to flexmark to get some behaviours closer to what I want, though the API looks a little daunting just now. At the very least, I'd like to be able to use flexmark-attributes in combination with HTML blocks, so that I could write, say:

<div>{.columms}
<div>{.column .is-4}
</div>
</div>

Rather than:

<div class="columns">
<div class="column is-4">
</div>
</div>

I suspect that is not possible either - any block-level HTML element in a markdown file basically short-cuts all further markdown processing.

Lots to think about, lots of refactoring to do, and lots more reading ahead of me.