dundalek / dinodoc Goto Github PK

Which results in broken Edit URL for reitit example, which needs workaround to specify repo+branch as global option instead of auto-detecting it.

Call graph:

• print-namespace
  • print-var
    • print-var-impl
      • var-source

When a namespace is mixed with clj and cljs (or cljc) there is no way to distinguish in which dialect the vars are defined. The resulting docstring is picked undeterministically (merge).

Get inspired by cljdoc which handles it pretty well. It determines which dialect is in majority and adds label to each var.

The original quickdoc works in babashka using clj-kondo pod, so generating docs should still work in babashka. The issue can be proper markdown parser #1, if we go with one like Flexmark (based on Java), we will need to make it into pod which adds extra effort.

Therefore I want to hold off on Babashka support, instead of having it and then removing it when proper markdown parser is introduced.

Asciidoc seens to be a popular alternative to Markdown. Recently Polylith changed readme and docs format to Asciidoc. Should we consider support for Asciidoc?

I always found markdown hitting the sweet spot naturally expressing common formatting. With Docusaurus there is MDX markup for richer elements. Asciidoc looks more complicated to me since it includes additional custom syntax for richer elements.

I wonder if translating Asciidoc to Markdown using Pandoc would work well as a preprocessing step?

Images have to be currently copied manually.

Possible solutions:

• have option like :copy-assets #"\.png|\.jpg"
• or just copy over images starting with ![]()

Wiki links to doc pages are not linkified, e.g. in ring example.

• wikilings are transformed already for vars, so maybe could add the pages hierarchy there during markdown processing

• alternatively remark plugin for docusaurus

  • https://github.com/landakram/remark-wiki-link
  • adding remark plugins to docusaurus
    • https://docusaurus.io/docs/markdown-features/plugins#installing-plugins

Currently markdown is processed using regexes which will likely result in some edge case issues (e.g. linkifying inside a fenced code block).

To handle it properly consider using proper parser. I am not aware of a good pure clojure parser, from Java ecosystem flexmark seems like a good candidate.

When there is a single namespace the nested hierarchy is not useful and takes extra clicks to expand.

For example instead of

com >
  org >
    project >
      foo
      bar

we could flatten as

com.org.project >
  foo
  bar

Is there also a way to perhaps have some items in sidebar expanded by default? With some heuristic to expand e.g. if there are less than 10 children items.

Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set collapsed to false:
https://docusaurus.io/docs/sidebar/items#expanded-categories-by-default

Code blocks using clj language not highlighted, only clojure works (e.g. reitit example).

• prism (the code highlight library) does aliases like Prism.languages.js = Prism.languages.javascript;
• but it does not have it for clojure
• pr that add zsh alias
  • PrismJS/prism#3738
• see if it can be hacked/swizzled
  • https://docusaurus.io/docs/markdown-features/code-blocks#supported-languages
  • npm run swizzle @docusaurus/theme-classic prism-include-languages
  • choose eject
  • PrismObject.languages.clj = PrismObject.languages.clojure;
• PR to prism would be nice, but v1 does not currently accept contributions

  We are currently working on Prism v2 and will only accept security-relevant PRs for the time being.

• docusaurus has generated-index, but we will probably want a custom one anyway
• https://docusaurus.io/docs/sidebar/items#generated-index-page