Skip to content
GitLab

[PROTOTYPE] Add a glossary for all our classes

Open Julien Déramond requested to merge main-jd-glossary-experiment into main

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.

Generation of glossary.data file

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 a glossary.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
    • 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

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 .accordions
  • 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.