Content
View differences
Updated by Parimal Satyal over 1 year ago
### **Context**
At the moment, OpenProject does not have a consistent and semantically sensible way of dealing with headings in long text fields. There are a number of known issues:
<figure class="table op-uc-figure_align-center op-uc-figure" style="width:100%;"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head" style="width:50.0695%;"><p class="op-uc-p">Current behaviour</p></th><th class="op-uc-table--cell op-uc-table--cell_head" style="width:25.0348%;"><p class="op-uc-p">Examples</p></th><th class="op-uc-table--cell op-uc-table--cell_head" style="width:25.0348%;"><p class="op-uc-p">Issue</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="width:50.0695%;"><p class="op-uc-p">It's possible to use all headings (including H1) in the text.</p></td><td class="op-uc-table--cell" style="width:25.0348%;"><ul class="op-uc-list"><li class="op-uc-list--item"><p class=" op-uc-p">Work package description</p></li><li class="op-uc-list--item"><p class=" op-uc-p">Meeting notes</p></li></ul></td><td class="op-uc-table--cell" style="width:25.0348%;"><p class="op-uc-p">The internal semantic structure of a document (a work package description, for example) can be incompatible with the larger structure of the page in which it is contained. For example, a work package header already is an h1, so something within the text cannot also be an h1.</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="width:50.0695%;"><p class="op-uc-p">Headings are rendered with fixed sizes and they are large.</p></td><td class="op-uc-table--cell" style="width:25.0348%;"><ul class="op-uc-list"><li class="op-uc-list--item"><p class=" op-uc-p">Work package description</p></li><li class="op-uc-list--item"><p class=" op-uc-p">Meeting notes</p></li></ul></td><td class="op-uc-table--cell" style="width:25.0348%;"><p class="op-uc-p">The headings are displayed as expected but the visual output is sub-optimal. The headings are very large and disproportionate to the size of the elements in which they are contained.</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="width:50.0695%;"><p class="op-uc-p">Headings not offered but <i>can</i> manually be entered in Markdown mode.</p></td><td class="op-uc-table--cell" style="width:25.0348%;"><ul class="op-uc-list"><li class="op-uc-list--item"><p class=" op-uc-p">Comments in the activity tab</p></li></ul></td><td class="op-uc-table--cell" style="width:25.0348%;"><p class="op-uc-p">The headings are simply not rendered. They are still maintained in the Markdown source, but they will be replaced by bold text in the comment itself.</p></td></tr></tbody></table></figure><br>
### Possible solutions
The solution will ideally solve three problems:
* Make it possible to use headings in text (including H1s), such that users are able to copy/paste existing documents if needed
* Make the headings semantically consistent within the text (in relative terms) and with the page in which it is contained (in absolute terms).
* For example, a work package description with headings h1, h2 and h3 and maintained as such in the source, but replaced with h2, h3 and h4 when viewing the the work package in OpenProject. On export, the original headings are used.
* We define new sizes for headings that are smaller and more proportionate with the rest of the elements on the page, compatible with Primer standards.
### Related ideas
* How might headings be handled in a distract-free edit mode, if we have one?
At the moment, OpenProject does not have a consistent and semantically sensible way of dealing with headings in long text fields. There are a number of known issues:
<figure class="table op-uc-figure_align-center op-uc-figure" style="width:100%;"><table class="op-uc-table"><thead class="op-uc-table--head"><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head" style="width:50.0695%;"><p class="op-uc-p">Current behaviour</p></th><th class="op-uc-table--cell op-uc-table--cell_head" style="width:25.0348%;"><p class="op-uc-p">Examples</p></th><th class="op-uc-table--cell op-uc-table--cell_head" style="width:25.0348%;"><p class="op-uc-p">Issue</p></th></tr></thead><tbody><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="width:50.0695%;"><p class="op-uc-p">It's possible to use all headings (including H1) in the text.</p></td><td class="op-uc-table--cell" style="width:25.0348%;"><ul class="op-uc-list"><li class="op-uc-list--item"><p class=" op-uc-p">Work package description</p></li><li class="op-uc-list--item"><p class=" op-uc-p">Meeting notes</p></li></ul></td><td class="op-uc-table--cell" style="width:25.0348%;"><p class="op-uc-p">The internal semantic structure of a document (a work package description, for example) can be incompatible with the larger structure of the page in which it is contained. For example, a work package header already is an h1, so something within the text cannot also be an h1.</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="width:50.0695%;"><p class="op-uc-p">Headings are rendered with fixed sizes and they are large.</p></td><td class="op-uc-table--cell" style="width:25.0348%;"><ul class="op-uc-list"><li class="op-uc-list--item"><p class=" op-uc-p">Work package description</p></li><li class="op-uc-list--item"><p class=" op-uc-p">Meeting notes</p></li></ul></td><td class="op-uc-table--cell" style="width:25.0348%;"><p class="op-uc-p">The headings are displayed as expected but the visual output is sub-optimal. The headings are very large and disproportionate to the size of the elements in which they are contained.</p></td></tr><tr class="op-uc-table--row"><td class="op-uc-table--cell" style="width:50.0695%;"><p class="op-uc-p">Headings not offered but <i>can</i> manually be entered in Markdown mode.</p></td><td class="op-uc-table--cell" style="width:25.0348%;"><ul class="op-uc-list"><li class="op-uc-list--item"><p class=" op-uc-p">Comments in the activity tab</p></li></ul></td><td class="op-uc-table--cell" style="width:25.0348%;"><p class="op-uc-p">The headings are simply not rendered. They are still maintained in the Markdown source, but they will be replaced by bold text in the comment itself.</p></td></tr></tbody></table></figure><br>
### Possible solutions
The solution will ideally solve three problems:
* Make it possible to use headings in text (including H1s), such that users are able to copy/paste existing documents if needed
* Make the headings semantically consistent within the text (in relative terms) and with the page in which it is contained (in absolute terms).
* For example, a work package description with headings h1, h2 and h3 and maintained as such in the source, but replaced with h2, h3 and h4 when viewing the the work package in OpenProject. On export, the original headings are used.
* We define new sizes for headings that are smaller and more proportionate with the rest of the elements on the page, compatible with Primer standards.
### Related ideas
* How might headings be handled in a distract-free edit mode, if we have one?