This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2023-08-08
Channels
- # announcements (1)
- # babashka (39)
- # beginners (44)
- # clj-kondo (10)
- # cljdoc (24)
- # clojure (49)
- # clojure-austin (2)
- # clojure-berlin (6)
- # clojure-europe (13)
- # clojure-nl (1)
- # clojure-norway (5)
- # clojure-uk (1)
- # core-async (11)
- # cursive (7)
- # datahike (3)
- # datalevin (2)
- # fulcro (1)
- # hyperfiddle (40)
- # jobs (12)
- # juxt (5)
- # lsp (9)
- # nyc (1)
- # off-topic (27)
- # re-frame (7)
- # releases (3)
- # shadow-cljs (9)
- # timbre (6)
- # xtdb (2)
- # yamlscript (1)
Is it okay to ask AsciiDoc questions here, or is there a better channel or another Slack workspace (or somewhere else)? To my question. I try to get https://docs.asciidoctor.org/pdf-converter/latest/theme/variables/ to work in my .adoc files, and I tried it out https://github.com/polyfy/polylith/blob/02df8828cc68fce3beda3d41b0d4885e35a33f63/doc/introduction.adoc?plain=1#L20-L26, but it didn't work, see https://github.com/polyfy/polylith/blob/02df8828cc68fce3beda3d41b0d4885e35a33f63/doc/introduction.adoc.
Ya sure! Here's the https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes/. Here's an example usage in https://github.com/clj-commons/rewrite-clj/blob/b8c4df1b819f060aa293ac65b9f86d53d42014de/README.adoc?plain=1#L6-L11. And https://github.com/clj-commons/rewrite-clj/blob/b8c4df1b819f060aa293ac65b9f86d53d42014de/doc/01-user-guide.adoc?plain=1#L142.
Thanks, this was very helpful!
If I understand right, a user-defined attribute is only visible within the document it's defined, and if so, if I want to use it in more than one file, is the solution to use https://docs.asciidoctor.org/asciidoc/latest/directives/include/ where I put the defined variables in a file, and then include it in the documents that use the attributes?
This approach is suggested https://github.com/asciidoctor/asciidoctor/issues/2130 so will start that way.
hrm, include looks really unsafe for untrusted adocs
We usually try to, kind of, within reason, match features with GitHub. They don't seem to currently support adoc include although there has been a https://github.com/github/markup/issues/1095 about it.
In that discussion are much tips/advice from the author of asciidoctor. So... maybe we could support include. But my feeling is that without GitHub support this would be awkward. Docs might not display as nicely on GitHub as they do on cljdoc but I think it is better for our users if they render the same content.
Okay, good to know. I have a long shell script that mimics the example in the documentation, and being able to use the content of those files (and the output files of them) would have been quite convenient, but is not crucial. I agree that it must render well on GitHub also to be worth implementing.
Is there an already defined attribute (e.g. {cljdoc-url}
or similar) for the URL of the generated cljdoc documentation, that I can use instead of a hard coded value, so that I don't have to refer to the hard coded url like https://github.com/polyfy/polylith/blob/640eae90c9445579005a48a0c2e3966e33c8f91c/doc/test-runners.adoc?plain=1#L61 (I use localhost for now, but that will change when a first version is published to cljdoc)? I can link to pages that is generated from what's in the doc
directory, using xref, but is it possible to link to the api doc (not the files on github, but the first page of the generated documentation, under the NAMESPACES heading)? I tried it https://github.com/polyfy/polylith/blob/640eae90c9445579005a48a0c2e3966e33c8f91c/doc/test-runners.adoc?plain=1#L58, but that didn't work.
Here's the relevant https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#link-to-api-docs. If I remember correctly I had cljdoc fixup any
urls to be relative. So I think these should work when previewing locally.
The only adoc attribute cljdoc defines is env-cljdoc
which is described https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#asciidoc-environment.
The nice thing about the fully qualified url to your api docs is that that url will also work if a user starts reading your docs from GitHub. They'll end up on cljdoc, but that's probably a better place to read your docs anyway.
Yes, I verified that a link like
...
is translated to this when I work locally:
...
My idea was to link to the cljdoc, so it's great that
works locally also!
The attribute {env-cljdoc}
is just a boolean. It would be nice if there was an attribute defined for
(in my case).Cool, glad I was right about that URL fixup.
> It would be nice if there was an attribute defined for
(in my case).
Ya but... if we have attributes that only work on cljdoc, then the reading experience on GitHub will suffer, no?
Okay, understand, just wanted to verify!
I guess this means that you need to do a search-and-replace of the cljdoc url, when preparing for a new release?
Well, for me it is not too bad, I typically have all my user guide docs in one file. I https://github.com/clj-commons/rewrite-clj/blob/b8c4df1b819f060aa293ac65b9f86d53d42014de/doc/01-user-guide.adoc?plain=1#L8 and use it throughout. Which for me is usually in https://github.com/clj-commons/rewrite-clj/blob/b8c4df1b819f060aa293ac65b9f86d53d42014de/doc/01-user-guide.adoc?plain=1#L133-L136.
But for cljdoc URLs you can use CURRENT
in place of your version. Cljdoc will replace CURRENT with the version of the docs that the user is currently reading on cljdoc. If coming from elsewhere (like GitHub) CURRENT
is replaced with the latest version of your lib.
Did you grok CURRENT
? (I think maybe the cljdoc library author's guide could clarify its behaviour a bit.)
Do you still have a pain point?
For rewrite-clj, I actually https://github.com/clj-commons/rewrite-clj/blob/b8c4df1b819f060aa293ac65b9f86d53d42014de/doc/01-user-guide.adoc?plain=1#L4. Which you might consider doing too.
A bit of a pain in the tush for you because I guess you'd have to redefine at the top of every .adoc
file, but for me usage was limited to one article.
Thanks for the help (again)! I didn't know about CURRENT
. I think this will work out quite well, and I will take a closer look at rewrite-clj.
Glad to hear it! I think I'll clarify the cljdoc author's guide when talking about CURRENT
.
I will!