What tool/framework makes nice command line tutorials?
October 22, 2020 3:32 PM Subscribe
I need to author some step by step tutorials for using command line tools together. I've seen some slick frameworks that make it easy for users to copy the exact command needed to run it in the terminal and see what the output should look like but am striking out on finding such a tool.
Katacoda looks close but is overkill - I don't need containers for users to be working in, just HTML they can read to get information from, an easy way to cut shell commands verbatim, and images of what they should see if things worked correctly.
Basically I need something like this:
[block of normal text explaining what the user is about to do]
[block of monospaced text that's the command to run] [easy button to copy the command]
[image of what the results should look like]
[block of normal text explaining what's significant about the results]
Repeat until the sequence of commands is complete.
Or:
[block of normal text explaining a challenge for the user to solve on their own]
[a hint that the user must click to see]
[a second hint the user must click to see]
[the solution in monospaced text (hidden until the user clicks on it)] [easy button to copy the command]
[image of what they should see (similarly hidden until the solution is clicked)]
[block of normal text explaining the challenge (similarly hidden until the solution is clicked)]
It looks like Jeckyl might do this with some coaxing? Is there an out-of-the-box framework that does this? I'm fine writing markdown but would prefer to avoid XML.
Katacoda looks close but is overkill - I don't need containers for users to be working in, just HTML they can read to get information from, an easy way to cut shell commands verbatim, and images of what they should see if things worked correctly.
Basically I need something like this:
[block of normal text explaining what the user is about to do]
[block of monospaced text that's the command to run] [easy button to copy the command]
[image of what the results should look like]
[block of normal text explaining what's significant about the results]
Repeat until the sequence of commands is complete.
Or:
[block of normal text explaining a challenge for the user to solve on their own]
[a hint that the user must click to see]
[a second hint the user must click to see]
[the solution in monospaced text (hidden until the user clicks on it)] [easy button to copy the command]
[image of what they should see (similarly hidden until the solution is clicked)]
[block of normal text explaining the challenge (similarly hidden until the solution is clicked)]
It looks like Jeckyl might do this with some coaxing? Is there an out-of-the-box framework that does this? I'm fine writing markdown but would prefer to avoid XML.
On more careful reading, it seems that you’ll need more than just normal markdown, but you would be able to write a Hugo shortcode to render the widget...but you would probably have to write the widget yourself.
posted by rockindata at 6:04 PM on October 22, 2020
posted by rockindata at 6:04 PM on October 22, 2020
Sphinx might be a good fit, and it has a copy-to-clipboard plugin. You can highlight code-blocks with Pygments. Depends if you like the default styles and if you have blog aspirations beyond what it can easily do.
posted by RobotVoodooPower at 6:29 PM on October 22, 2020
Not sure about show/hide blocks -- the HTML details tag might be good enough, or there might be a plugin.
posted by RobotVoodooPower at 6:29 PM on October 22, 2020
This thread is closed to new comments.
A cheap and easy way to do this is through gitlab or github pages.
posted by rockindata at 6:01 PM on October 22, 2020