Our great sponsors
-
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
oauth2-proxy
A reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.
-
-
KeenWrite
Discontinued Free, open-source, cross-platform desktop Markdown text editor with live preview, string interpolation, and math.
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
-
-
Markdown can literally be code. RMarkdown is this. Before I learned of RMarkdown I had written something to extract code blocks with filenames that are visible in the rendered page (since hiding it at the end of the first triple backquote codefence isn't great for visibility). I'm currently working on a notebook tool. https://github.com/ResourcesCo/macchiato/blob/main/scripts/m... https://github.com/ResourcesCo/notebook
Markdown can literally be code. RMarkdown is this. Before I learned of RMarkdown I had written something to extract code blocks with filenames that are visible in the rendered page (since hiding it at the end of the first triple backquote codefence isn't great for visibility). I'm currently working on a notebook tool. https://github.com/ResourcesCo/macchiato/blob/main/scripts/m... https://github.com/ResourcesCo/notebook
The "insanity" of the section characters isn't really … it's just that the adorning character doesn't matter so much. (Other than it has to be the same.)
The picture-of-a-tweet nails it, but the author misses the point. It's not "we have Python devs" it's "reST has the best syntax for extensibility": if you need to start doing some sort of macro or pre-processing, reST's syntax is cut out for that. M↓ is not; you'll need to do it out of band. Or, to put it differently, reST's directives offer extension hooks.
> You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.
We throw ours behind Github, I think using https://github.com/oauth2-proxy/oauth2-proxy ; then Github is our IAM.
Honestly, while I think reST has a more cleanly thought out syntax that will allow you to grow the complex use cases docs will inevitably hit … the tooling just isn't as good, IMO. Markdown parsers are prolific … reST … not so much, particularly outside of Python. (And IMO, docutils in Python is not very easy to use if you want fine control over parsing & output. It's there, but just hard to take advantage of.) M↓'s syntax is also somewhat limiting: there's just not a lot it can do. (Admonitions, in particular, are useful in tech docs and missing.) There's always HTML, … but that's just not the same.
(I've no experience w/ AsciiDoc.)
The creator of Pandoc is creating a markup language worth looking at: https://djot.net/
It's in JSON at least by default. Here's an example: https://github.com/tensorflow/examples/blob/master/courses/u...
> These look great! Were these generated with KeenWrite?
Thank you! My sci-fi story, autónoma, is the reason I started to work on KeenWrite, and can be fully generated from within the app. The others could be edited in KeenWrite, but there'd probably need to be some work done to get the HTML/CSS preview panel to display the various annotated sections correctly. Speech bubbles (::: bubbletx and ::: bubblerx), for example, currently work in KeenWrite, but the spectrographic lines in the Impacts Project would need to have special CSS written to render correctly in the preview.
> The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.
Teaching people to separate content from presentation takes a lot of effort. That's also a process problem. You could ask people to provide feedback by adding notes into the PDF, rather than editing it directly.
At some point it'd be nice to see real-time collaboration added to KeenWrite, which would go a little ways to helping solve multiple users editing a single document:
is generated from this pytest source: https://github.com/TriOptima/iommi/blob/master/docs/test_doc...
Is that how rust documentation works?
The meaning is the same; the syntax is different. All triple-backtick codeblocks in doc comments, unless annotated 'ignore', are run as tests when you run `cargo test`. So from this file[0], this doc page[1] is generated. And there's more flexibility than 'run or ignore' too, e.g. one on that page is marked ```compile_fail,E0277 to fail the test if it compiles or has a different compilation error than expected. And then every code block known to be runnable has a Run button you can click to open the snippet in the Rust Playground.
These are API docs, but mdBook[2], which generates documentation that looks like this[3], has a test command which checks the code blocks the same way.
[0]: https://doc.rust-lang.org/stable/src/alloc/string.rs.html#76
[1]: https://doc.rust-lang.org/stable/std/string/struct.String.ht...
The meaning is the same; the syntax is different. All triple-backtick codeblocks in doc comments, unless annotated 'ignore', are run as tests when you run `cargo test`. So from this file[0], this doc page[1] is generated. And there's more flexibility than 'run or ignore' too, e.g. one on that page is marked ```compile_fail,E0277 to fail the test if it compiles or has a different compilation error than expected. And then every code block known to be runnable has a Run button you can click to open the snippet in the Rust Playground.
These are API docs, but mdBook[2], which generates documentation that looks like this[3], has a test command which checks the code blocks the same way.
[0]: https://doc.rust-lang.org/stable/src/alloc/string.rs.html#76
[1]: https://doc.rust-lang.org/stable/std/string/struct.String.ht...