How to handle special pads

[DerMolly]

Currently we have some pads that are loaded from disk

• release-notes
• features
• yaml-metadata
• slide-example
• imprint
• privacy

and the admin can create more of these pads by creating files at /public/docs/<yourpad>.md

In the future we want to add

• banner (#189, #190)
• intro (#125)

to that list.

The problem is that the admin can overwrite user pads with one of the (not very helpful, but anyways) aliases above. What could we do about that?

@davidmehren proposed changing the behavior to the following:

1. only have the above mentioned special pads and not any arbitrary other special pads
2. put all special notes under /<special_note> and prevent /n/<special_note> from being created (and rename possible old notes to other names)

[DerMolly]

We wouldn't need to add /r/<pad> and we would remove any confusion from having both /imprint and /n/imprint and such

[DerMolly]

@mrdrogdrog and @ErikMichelson proposed to add an api call GET /special/<special_file> to get those files from the backend and show them in read-only manner

[ErikMichelson]

Why not use /r/pad and prevent creation of /n/pad anyway?

[SISheogorath]

How does that make anyone's life easier? Now we not only have to check if a document exist and serve it, we also need to make sure that that pads with the same name don't get created.

How do we handle it when a pad already was created with that name? Do we delete it? Do we overwrite it?

I think we make things unnecessary complicated by adding an extra path for those things. Just use the existing infrastructure and functionality. Also what do we with notes that have been already created by people using the docs directory? Do we move those? Do we redirect old URLs to the special URLs now?

Why should we not simply use what we have and make it as easy as 3 booleans for terms, privacy and impress in the config? And prospectively maybe two additional strings for the intro text and a banner title.

[DerMolly]

How do we handle it when a pad already was created with that name? Do we delete it? Do we overwrite it?

this question was already answered

[SISheogorath]

To be honest, I still don't see the problem we try to solve.

The problem is that the admin can overwrite user pads with one of the (not very helpful, but anyways) aliases above. What could we do about that?

If an admin does it intentional, then no one can prevent them from doing it by changing the database. If an admin does this by accident it's as simple as removing the file and use revisions to reset the note.

I don't see how any of this justifies a new API endpoint that gets special treating from both, backend and frontend.

[DerMolly]

user pads and system markdown files are two very different things. The system markdown files were hacked in the pad system because that was easy and simple to add, but it's neither a very good nor intuitive idea. The currently proposed idea is to separate this hack and make a clean distinctions between those two in the future. With 2.0 we have the great opportunity to right these errors of the past and make the whole project easier to grasp by future contributors. The argument in the past we've done it like that is nearly always a bad sign, because if that's the only reason, there is no reason at all.

[SISheogorath]

And I think here we have fundamentally different perspective on the base of our discussion. To me one of the beauties of CodiMD is that a markdown document is a markdown document is a markdown document.

Those "system notes" are not more than notes with a special name. And when we treat all markdown documents equal we make ours and other people life a lot easier. (And most people I heard talking about the fact that you just drop those file in there and they become pads, love that idea, but maybe I'm in strange bubble.)

For the initial problem I would even argue, that due to the fact that I always use CodiMD without the free-url-mode and explicitly recommend against using it, it never really accrued to that one could overwrite other people's note.

[SuperSandro2000]

There are probably many pads in free url mode and most end users like that behavior. It mirrors etherpad and makes adoption a lot easier.

I don't see the problem when overwriting pads. You don't add new pads everyday normally and if you overwrite one you can just change its URL or copy the content over to another pad.

I would just leave it as it is right now.

[DerMolly]

I though about this just now and I have two points to make:

1. The special pads fall into two categories
   1. Tutorial pads (/features, /slide-example & /yaml-metadata). These need to be read-only pads in the editor, to show users show things are accomplished.
   2. Info pads (everything else). These should most likely be shown in the render-only mode (e.g. /s/imprint) as the how is not important, but the what.

With these things said, I think it would be best if we link to this pads like that. So tutorial pads should always link to /n/$padname and info pads always to /s/$padname. But that's more for us to remember as I would dis advice against any auto reroutes from /n/$padname to /s/$padname or vise versa. Maybe we want to link all of the special pads to /$padname and let the frontend work out what should go where?

2. All those special pads need a special handling in all pad related matters and should be fetched from disk. If they don't exist a blank page (maybe some help text for the admin) should be shown. The 2.0 release could also just contain every of those special pads with a default content, if they're meant to be changed (e.g imprint). Anyway in the upgrade process from 1.6/1.7 to 2.0 any pads already named as any of those need to be renamed.

That way we don't have any specialty in the api, but just in the backend code.

TL;DR

Let all the magic happen in the backend and bring default content (either what should be there or an explanation how to change them) for all the special pads.

[mrdrogdrog]

So you say "treat special pads as regular pads in the frontend?". If that implies "the frontend redirects from /features to /n/features_$language" then I'm fine with that.

I'm totally fine with treating the special pads as regular pads as long as we handle links like "/features" in the frontend logic.

[DerMolly]

That's something I forgot while writing this, but yes I guess that would be a good idea too. Of course the backend would then need to handle all the translated pads differently, too.

[ErikMichelson]

We agreed on the following:

• Release notes and yaml-metadata won't be special existing pads in HedgeDoc 2 anymore. The release notes can be found on the webpage and on GitHub while the yaml-metadata explanation is in the docs.
• Features and Slide example will become a special page baked into the frontend source code. This allows them to be translated. Additional there could be a button "Create an editable copy of this note".