Symphony.

That's not entirely true: our version has diverted from Craig's original in Symphony 2.2.5 already. The idea is to merge both approaches again.

Documenter 2.1

This is the current situation:

• Craig's original extension has been moved to the Symphonist organisation on Github. It has partly been updated for 2.3 but doesn't work reliable yet (there are some layout problems regarding buttons and drawers).
• There is Johanna's an my fork which is not Symphony 2.3 compatible yet but which incorporates advanced styling and behaviour of the documentation sidebar (collapsible sections, better typography) – this is all JavaScript and CSS based.

There is one conceptual problem at the moment:

While general documentation about using Symphony or a text formatters is portable between different builds, all texts are stored inside the database as if they were unique to that install. It would be far easier to have the documentation stored in the filesystem (e. g. /workspace/documentation/) so that it could be versioned using Git and could be moved between installs via drag and drop.

Our idea

1. We'd like to update our advanced styles to the new drawer layout available in Symphony 2.3.
2. We'd like to move the documentation to the file system.
3. As a consequence we'd like to change the backend logic and attach texts to backend page (not vice versa as it's done at the moment): texts could be attached as file references and could be individually ordered in the backend for each page (using a Duplicator for example).

Our problem is that we don't know how to approach step 2 as there needs to be some kind of import/caching: if the documentation was stored in the filesystem, it would be possible to write Markdown (or any other markup) in your preferred editor directly. These texts need to be converted to HTML and cached for the usage in the documentation drawer (we don't want to convert the files on each page view).

What we do know is how update the styles and how to build the needed interface interactions in step 3. We'd need help for the essential bridge in the middle.

By the way, Craig also created a Text Upload Field which uses a similar approach (this is where the idea of moving texts to the filesystem came from). Maybe this can be used as a blueprint.

@Nils It should be possible to use any of the available client-side markdown libraries to convert to HTML on the client instead of doing it on the server and caching it.

But why should we process Markdown each time when the documentation is viewed?

How much does Markdown processing cost per page view?

Creating a reliable caching file system is way more expensive than a few milliseconds.

That certainly depends on the length of your text and on the chosen Markdown variant.

The thing is that the documentation is added to the pages even if the drawer is closed. That means Markdown (or any other processor) would have to run on each page load, when editing, after saving, when viewing the publish index etc. You will certainly notice a slowdown (unless the documentation will only be loaded on request).

By the way, when I talk about caching I think that on demand caching would be sufficient (something like a sync button).

Ok, first things first. I have compared the two versions (symphonists/integration branch and the one on Johanna's github account) and found that the changes on the second one should be easily incorporated into the first one (which is functional under 2.3 and thus should act as the base in my humble opinion) just as Nils mentioned already it is mostly CSS and Javascript changes. I suggest I go ahead and produce a merge between the two and then we can follow up from that. Who is going to be the coordinator? Are you up for it Nils?

Yeah, I can do that.

@Nils I'm pretty sure we talked at some length about updating the documenter for 2.3, hence my commits here (https://github.com/symphonists/documenter/commits/integration/) so hopefully you won't need to start from scratch. I thought I was doing you a favour ;-)

@Nils, Great! Are you a collaborator on the symphonists repository? Should pull requests be directed there?

@nickdunn The integration branch from the symphonists repository will act as the base, the extension works nicely on 2.3 os no need to redo the work indeed :)

I thought I was doing you a favour ;-)

You did – but still I need to port our custom styling. You should have considered doing this all along :-P

Are you a collaborator on the symphonists repository?

Yes, I am. Will push the updated styles later today.

Should pull requests be directed there?

Yes.

All merged: https://github.com/symphonists/documenter

You guys are quick! Many thanks for this!

Sorry, still have a problem. When I try to use the unicode character Open Box: ?, it get’s converted into a question mark after saving. Is this a unicode problem in the database?

EDIT: same thing happens with it here in the forum comments :)

EDIT 2: Saving it as ? works once, as long as I don’t resave it. Then it get’s destroyed again.

EDIT 3: I’m using Markdown with Smarty Pants.

Does the font support it?
Does UTF-8 support it?

Nils, many many thanks on the work on this! Job well done!

@Nils

The font I use in the backend does support it (otherwise it wouldn’t work before resaving).

It seems to be part of UTF-8, since it does have a UTF-8-hex- and decimal value.

I guess it gets lost in the markdown conversion progress. My workaround is to edit my Documenter contents locally, with the Open Box as an HTML entity, so it’s not really a big deal. Only slightly irritating at first. :)

That error is probably because the CREATE TABLE statement doesn't specify the table collation or character set to be UTF-8, so the table has most likely been creating using MySQL's horrible default of latin1, which will eat unicode characters.