search

clj-commons / marginalia

Ultra-lightweight literate programming for clojure inspired by docco
https://clj-commons.org/marginalia/
813 stars 82 forks source link

[Idea] Ways to style the docs based on metadata on `def`s #188

Open bshepherdson opened 5 months ago

bshepherdson commented 5 months ago

I'm documenting an "interface" namespace that's intended to be used by other parts of the codebase. It has many healthy functions that will be around for the longer term, but some need a bit of work, and others only there to support some legacy use cases.

I'd like to be able to put Clojure metadata on the vars like ^:legacy or ^{:health :smelly} and then to define custom CSS classes in Marginalia that will style the docs and/or code regions for those functions in some fashion, perhaps adding a red border on the left edge.

Less nice, but still workable, would be including HTML tags or similar annotations inside the docstrings to achieve the same effect.

seancorfield commented 5 months ago

Interesting suggestion. Do you have more concrete ideas about how specifically you imagine this working from a user perspective?