Embedding Code Into Documentation

We use github gists and it works pretty well. For instance on our KB

I think the question needs some more clarification, what kind of documentation are you talking about? For example online docs in which case what kind of platform?

Since most of my stuff is code and technical, I use plugins to format the code and use markdown files. However there are other ways you can do it using something like GitHub code snippets and embedding them so you can update the code in one place and it will automatically appear refreshed in documents.

Just a couple of thoughts.

Yes, it's mildly annoying. No, I wouldn't pay to fix this.

Not an issue for us at all. We use Phabricator to manage all our development tasks, and tickets (and merge requests) are all linked to the repo so we can narrow down to the actual live code at any time if we reference a ticket or PR in our Phabricator Wiki documentation.

I'm building a notebook system that may exactly solve your painpoint, it's called Starboard

I have had this issue in the past, and Elixir solves this in a really great way. Basically if you put example code of running a function from the REPL into a doc block, that code automatically gets run when you run tests on that file!

E.g. if you've defined a function that squares numbers and then you put the following into its @doc string:

@doc """
This function takes one argument and returns that number squared. For example:

iex> Enum.map([1, 2, 3], &my_square_function/1)
[1, 4, 9]
"""

Then your documentation will cause your tests to fail if your example ever gets broken by changes to your code. Some other modern languages have similar tooling built in and I could definitely see using 3rd-party tooling to do it if you're working with an older language that doesn't do this.

(note: in the example, it should be @doc, without the [](/doc). It seems I've hit an edge case in IH's handling of pre-formatted code blocks.)

Using markdown, a JS script creates virtual files of the code snippets after which the user can edit them live on code sandbox. It doesn’t solve the up-to-date issue but IMHO apis shouldn’t change that often.

Yeah I have no idea how. I've been using markdown, but I wish it was more live and runnable