Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add option to ingest clj file comments as markdown #175

Open
metasoarous opened this issue Oct 15, 2021 · 0 comments
Open

Add option to ingest clj file comments as markdown #175

metasoarous opened this issue Oct 15, 2021 · 0 comments

Comments

@metasoarous
Copy link
Owner

metasoarous commented Oct 15, 2021

This is something I've talked about for a while (and is actually already in progress), and is an important step to completing the vision of Oz as a tool for the "namespace as a notebook" concept.

I'm debating about whether this should be the default option or not. Again, it's something I've stated I would be doing, and I don't think our collective philosophy on "changing" API functions really applies in this case, since we're still taking clojure code and spitting out html; (We're not taking a function that used to take sheep and stone and producing wool into one that produces corn). It's also just not very ergonomic right now to have to embed your markdown in [:md ...] hiccup blocks (for lots of reasons). Finally, Oz is still in alpha, and while I have every intent of not breaking anything (or even really changing behavior like this in unexpected ways), this is exactly the sort of wiggle room I've been trying to preserve with this very long running line of alpha releases. So everything here is pointing to me going ahead and making this the default, but it may be a good idea to add a function which allows for setting global Oz options, so that this behavior can be turned off without too much trouble on the part of the user if need be.

I believe the correct behavior here is more or less what Marginalia embraced: Only lines that specifically start with ;; will be processed as markdown. Lines that look like ;; some indented comment or ;(some-code ...) or even ;;some comment I don't want in the output will not be processed as markdown. This probably should be shown inline with the code if #135 is enabled, but in the code blocks, and not as html.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Development

No branches or pull requests

1 participant