Support rendering tables of wiki front-matter
Problem to solve
When planning our development work, my team often creates large tables in order to compare options. Each table has a different set of columns (a column for each factor we're comparing) and rows (a row for each option we're comparing).
I'd like to be able to do this within GitLab, so my team doesn't have to use other software for this part of the planning process. We've tried using Markdown tables for this, but it becomes cumbersome to edit when there are more than a handful of rows or columns — adding a column requires editing every row (even if the cell is empty); adding a row requires editing every other row if you want to keep the pipes aligned so it's readable. And the textarea's word-wrapping makes it difficult to tell which row is which when the row is more than about 100 characters. So I've been looking for a better way.
Intended users
User experience goal
Project planners should be able to easily create and edit tables with many rows and columns.
Proposal
GitLab already has basic support for front-matter in wiki pages. I'm thinking a Minimum Viable Change to facilitate this use-case would be to add a syntax for performing a query of the front-matter in each wiki page, and rendering it inline as a table.
Further details
For example, I would create many wiki pages in the Graphics-Library
subfolder, such as this one called BGFX.md
:
---
Repository: '[bgfx](https://github.com/bkaradzic/bgfx)'
License: BSD
Language: C++
Direct3D 11: ✅
Direct3D 12: ✅
Metal: ✅
OpenGL: ✅
---
My detailed notes about this project…
Then I would create a "Graphics Library Summary" wiki page containing some introductory text and a simple query syntax like this:
{{{#!wiki_page_table path="Graphics-Library"}}}
Which would render a table like this:
Title | Repository | License | Language | Direct3D 11 | Direct3D 12 | Metal | OpenGL | Content |
---|---|---|---|---|---|---|---|---|
BGFX |
bgfx | BSD | C++ | My detailed notes… | ||||
Sokol |
sokol | zlib | C | My other detailed notes… |
The table would contain a row for each wiki page in the specified wiki folder. The Title column would be automatically generated (a view link and an edit link), followed by a column for each key in the front-matter, followed by a trimmed preview of the wiki page's content.
That way, GitLab takes care of the table formatting for you, so you just need to create wiki pages and populate the front-matter, instead of fiddling with Markdown table syntax. To add a new row, just create a new wiki page. To add a new column, just add a new key to the front-matter of the relevant wiki pages.
Permissions and Security
- Anyone with permission to edit a wiki page should be able to insert the proposed tag
- Anyone with permission to view a wiki page should be able to see the table rendered by the proposed tag
Links / references
-
#223046 — Syntax based on Trac WikiProcessors.
- Similar to https://trac-hacks.org/wiki/WikiTableMacro
- #29043 (closed) — The Title column should use the title from the front-matter.
- #209977 (closed) — Would make it easier to create/edit front-matter.
-
#25105 — Gollum provides a
<<Navigation()>>
macro that renders a list of wiki pages in a folder (but it doesn't include each page's front-matter keys like proposed on this issue)