# Introduction S2MD is developed to assist with live coding sessions in the shell. S2MD consists of several shell scripts to automatically copy code which is entered in the shell into a HackMD note. There are also scripts to add chapter titles, exercises and other text to the note document. To make S2MD work a few settings are necessary as well as the installation of an interface between shell and HackMD. # Configuration ## Setup shared history For S2MD to work the history of shell needs to be shared amongst all open instances. This is by default not the case. Settings differ between bash and zsh. ### zsh Add the following two lines to the .zshrc file in the home directory. ``` setopt inc_append_history setopt share_history ``` This can be done with for instance nano. Go to your home directory and enter: ``` $ nano .zshrc ``` Copy and paste the above two lines anywhere in the `.zshrc` file. Close all instances of the terminal and reopen. The history is now shared. This can be checked by opening two instances of the terminal and enter a command in one of those, for instance `echo "test"` and enter `history` in the other. The command `echo "test"` should be the last line of the output in the second terminal instance. brew install fswatch ### bash Add the following two lines to the .bashrc file in the home directory. :::warning :warning: **WARNING:** This code has not been tested ::: ``` # Avoid duplicates HISTCONTROL=ignoredups:erasedups # When the shell exits, append to the history file instead of overwriting it shopt -s histappend # After each command, append to the history file and reread it PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND$'\n'}history -a; history -c; history -r" ``` This can be done with for instance nano. Go to your home directory and enter: ``` $ nano .bashrc ``` Copy and paste the above two lines anywhere in the `.bashrc` file. Close all instances of the terminal and reopen. The history is now shared. This can be checked by opening two instances of the terminal and enter a command in one of those, for instance `echo "test"` and enter `history` in the other. The command `echo "test"` should be the last line of the output in the second terminal instance. ## Connect to HackMD To connect to HackMD hackmd-cli is used. hackmd-cli is available in the [npm software registry](https://docs.npmjs.com/about-npm). If you do not have it already you need to [install](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) the npm command line interface first. With the npm command line interface install hackmd-cli. ``` $ npm install -g @hackmd/hackmd-cli ``` Setup a connection to hackMD with an API. First an access token should be set. It can be created one your hackMD page. hackmd.io -> Setting -> API -> Create API token. Copy the token. Now login on your terminal. ``` $ hackmd-cli login ``` You will be prompted to enter your API. By doing so, the access token will be saved in `~/.hackmd/config.json`. ## Content Content such as chapter titles, exercises and other text can be prepared beforehand and should be stored in a content folder. For the Software Carpentry Unix and Git lessons these materials are available. The actual note file is stored and maintained on you local machine in the content folder. When changes to this file are made the content of this file is uploaded to HackMD. Code, chapter titles, exercises and other text is appended to the end of the note file. Markdown formatted text can be added to this file by hand; for instance some explanatory text can de added at the start of the note file. ## Settings ### Settings file There are a few settings that need to be set beforehand. These are stored in a file called `s2md-settings.sh`. The following settings should be modified: * `s2md_content` = the directory in which the content is stored. * `s2md_id` = the hackMD note ID number. This is part of the note URL after the slash and before the question mark (if present). Open `s2md-settings.sh` with a text editor and change these variables if necessary. For example open settings file: ``` $ nano s2md-settings.sh ``` Change settings in this file: ``` s2md_content = "~/content/" s2md_id = "hl4dGUpOQTSoPBfQmI0g" ``` ### Ignore file The file `s2md-ignore.txt` contains a list of commands which should be ingored by S2MD. When these commands are executed in the terminal, they will not be added to the notes document. Each command that should be ignored is entered on one line. Every command that starts with a exact match of the command will be ignored. This file is populated with a standard set of commands, but commands can be added or removed from the list. Example: ``` clear bash s2md.sh bash addch.sh bash addex.sh bash addtx.sh ``` # Usage ## Start tracking terminal entries To start tracking the history of the shell use this command without parameters: ``` bash starttrack.sh ``` When using aliases: ``` track ``` ## Add chapter titles To add a chapter title `bash addch.sh` can be used followed by the chapter number. The chapter titles are retreived from the file `chapter-titles.md` in the content folder and the number identicates the line number in this document. For example to add the first chapter title to the notes document: ``` bash addch.sh 1 ``` When using aliases: ``` sac 1 ``` ## Add exercises To add an exercise `bash addex.sh` can be used without parameters. A numbered list of available exercises in the contents folder is returned (given all the files names start with `ex-` and end with `.md`). Now enter the number of the right exercise. Exit the list if nessesary with Cntl-C. For example: ```bash bash addex.sh ``` Will return: ``` Please select an exercise from this list. 1) /Users/reinder/content/ex-ch1-absolute-vs-relative-paths.md 2) /Users/reinder/content/ex-ch1-explore-more-ls-flags.md Enter Exercise Index ID: ``` When using aliases: ``` sax ``` trackhist.sh addtext.sh addcom.sh addex.sh ignore.lst # Aliases To shorten the commands aliases can be used. Most confeniently the aliases are also added to the `.bashrc` or `.zshrc` file. The can also be entered in the terminal itself, but in that case will only work in that particular instance. Which aliases to use is of course up to you, but here are some suggestions. Remember to add the aliases also to the ignore list. ``` alias sac='bash addch.sh' alias sat='bash addtx.sh' alias sax='bash addex.sh` ``` Now the title for chapter 1, for instance, can be added with the command `sac 1` and an exercise can be selected with `sax`.