Feel free to close it if it pollutes the PRs to review, I mainly create it to share the idea and to not to lose how to generate the *.data
file with grep
Linked to https://github.com/twbs/bootstrap/issues/36978
Based on https://github.com/twbs/bootstrap/issues/36978#issuecomment-1233767886 and other feedback regarding the benefit to have a glossary some day containing all of our classes, I tried prototyping few things around that.
glossary.data
file
Generation of Used grep -Eoh "\.[[:alpha:]]([[:alnum:]]*\-)*[[:alnum:]]*" dist/css/bootstrap.css | sort -u
$ cd build
$ node generate-glossary.js
Algorithm
- Script will extract data (classes) from
dist/bootstrap.css
and store them in aglossary.data.temp
file - Then, it will merge it into
glossary.data
- New values will be added in the sorted list of classes names as a
key:value
system:- Key: class name (e.g:
.accordion-body
) - Value: URL /components/accordion/#example
Check if we don't need an array of URLs. Some classes like .collapse
or other could be explained at different locations in the docs
- Key: class name (e.g:
- If the classes names are in both files, script will keep the one from
glossary.data
that could contain URLs - Obsolete values will be removed from
glossary.data
- New values will be added in the sorted list of classes names as a
Example:
.accordion-body:/components/accordion/#example
.accordion-button:/components/accordion/#example
.accordion-collapse:/components/accordion/#example
[...]
.border-0:/utilities/borders/
[...]
Note: Filling this file the first time will hurt but it should be done only once (and maintained after)
Live preview
TODO
The rendered page should be a nicer list than in my prototype:
-
Improve the script to be more efficient -
The script should remove comments from dist/bootstrap.css
to avoid having.com
and.map
in the list -
.accordion
should be displayed before other.accordion
s -
Check if array is a good way of displaying all of that -
Try grouping classes by first letters (with an anchor link by letter to jump to the dictionary more easily)
-
-
Don't know how Algolia would handle this page. It could help with classes that are described like .offset-md-*
,.gy-*
, etc. -
When must the script be executed "manually" and by CI jobs? It needs dist/bootstrap.css
to be generated. Could be done for each PR that contains CSS modifications🤷 -
If the URLs contain anchors to be more precise, would it be more difficult to maintain since we could change/move the sections in the docs and not thinking to modify this glossary.data
file. -
Couldn't we display the deprecated classes as well? Could help for migrations. But it would require to have the glossary.data
from v4 saved somewhere.