DEV Community

Alex Adam
Alex Adam

Posted on • Originally published at reactivedoc.com

Write Interactive Documentation with Templates and Parameters

Let's say you want to do a local port forwarding via SSH, but you don't remember the command. You do a quick search on google and find something like this:

ssh -L 8080:localhost:80 user@10.20.30.40
Enter fullscreen mode Exit fullscreen mode

But, in your case, the SSH server doesn't run on the standard port, so you have to specify the custom port. You do another quick search and assemble the full command (in your head or in a text editor that acts as a buffer):

ssh -L 8080:localhost:80 user@10.20.30.40 -p 1234
Enter fullscreen mode Exit fullscreen mode

Now you have a generic example, and you have to replace the key parts in the command to make it work. So you have to replace the local port, remote port, remote user, remote ip and the SSH port.

A few copy-pastes later and you realize you forgot how it works: local_port:ip:remote_port OR remote_port:ip:local_port ? Google saves you again:

ssh -L LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER
Enter fullscreen mode Exit fullscreen mode

You just spent 10 minutes gathering or refreshing some valuable info. You also spent valuable time on editing or copy-paste parts of the command in order to customize it.

ReactiveDoc can help you write documentation with templates and parameters. Why is this useful? Because it saves you a couple of minutes next time you'll want to reuse this command.

Let's start with the basic command as a template:

Image description

Add some basic explanation from https://linux.die.net/man/1/ssh and a link to this excellent resource

Image description

Then add a Number Input, and change the label value to "Local Port", variableName to "local_port" and set 8080 as defaultValue, like this:

Image description

In the command template, replace 8080 with {{local_port}}

Image description

Now, add a Text Input for the destination IP, then replace 'localhost' in the template with the {{destination_ip}} variable:

Image description

You can extract each command's part as a parameter:

Image description

Export this document as an HTML page and, next time you want to do a SSH port forward, just open it with any browser, set the parameters, click on the 'copy' button and paste it in a terminal. 2 minutes saved!

You can also share this HTML file with your team (they don't have to install anything to run it - it works in any browser) or host it on a local server as a static page.

Try ReactiveDoc Now!

Discussion (0)