mkdocs sort functionality

[plbremer]

Followup from #99

Adds sorting functionality to tables in mkdocs documentation.

[sujaypatil96]

Might need to hold off on merging this one till we decide how sorting gets applied to hierarchically indented tables @cmungall?

[cmungall]

Good point @sujaypatil96

It can be configured at the html level:
https://tristen.ca/tablesort/demo/

But I don't know if it's possible from the markdown. Maybe a feature request for mkdocs?

[sierra-moxon]

@sujaypatil96 - can you give me an update on this? Is it ready to merge with or without hierarchical table decisions? thx in advance! :)

[sujaypatil96]

Yup, I think is good to be merged as is @sierra-moxon.

We're already using table sorting in some linkml schema repositories like the NMDC Schema: https://github.com/microbiomedata/nmdc-schema/blob/main/mkdocs.yml#L20-L22

The problem with sorting hierarchically indented table still exists, but that doesn't need to block this PR.

[sujaypatil96]

Although, perhaps, now that I think about it -- top level is not the best place for tablesort.js. I think we can use this opportunity to come up with a structure for another folder nested under src/, say scripts/ where schema developers could put in ad-hoc JS, Python, jinja, etc.?

CC: @sierra-moxon

[dalito]

Maybe a src/docs/files/javascript folder? From there the files would be copied correctly with the current make file.

In mkdocs.yml you would reference e.g. a local mermaid copy like this:

plugins:
  - mermaid2:
      version: 11.4.1
      javascript: javascript/mermaid.min.js

[sujaypatil96]

@dalito that's a fair proposal as well. My only concern is the "loose" definition around what the contents of each of these folders is/should be? Like this folder is called src/docs/files/ so it intuitive to have custom scripts in there, or if we should strictly restrict it to documentation files like md, rst, etc.

[dalito]

... or if we should strictly restrict it to documentation files like md, rst, etc.

Yes, I think limiting the change to additional files for the documentation would be fine for this PR.