feat: chapter 31 - the power of terminal editors (#196)

* wip: chapter 31 - the power of terminal editors

* wip: add the Caret component

* wip: insert commands completed, operators next

* wip: more work on the chapter

* chore: developer guide and caret improvemnts

* chore: add annotated command to dev guide

* wip: add the asciinema preview

* wip: proof reading complete

docs/06-advanced-techniques/31-the-secure-shell/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: 'The Secure Shell'
 slug: '/part-6-advanced-techniques/the-secure-shell/'
-chapterNumber: 33
+chapterNumber: 3
 ---
 
 So far we have been using the shell to operate on our local machine. We can use _Secure Shell Protocol_, or _SSH_, to open a secure network connection to a remote machine and use the shell to work on that machine.

docs/zz-developer-guide/components.mdx

@@ -0,0 +1,103 @@
+---
+title: Components
+---
+
+This page shows the custom components that are available for Effective Shell. These are primarily used to improve the reading experience for code samples.
+
+To add more components to this page, please check the `src/theme/ReactLiveScope/index.js` file, which has been swizzled as per the guide at [Docusaurus - Code Blocks - Interactive code editor](https://docusaurus.io/docs/markdown-features/code-blocks#interactive-code-editor). Each custom component you want to use must be included in this file.
+
+## AsciinemaPlayer
+
+The `AsciinemaPlayer` component is renders an [`asciinema`](https://asciinema.org/) recording. Note that the recording file must be available to be served to the browser, so it will normally live somewhere in the `static` folder.
+
+First, import the component:
+
+```jsx
+import AsciinemaPlayer from '@site/src/components/AsciinemaPlayer/AsciinemaPlayer.tsc';
+```
+
+Use the component as below:
+
+```jsx live
+<AsciinemaPlayer
+    style={{'width': '800px'}}
+    src="/casts/483782.cast"
+    poster="npt:0:23"
+    autoPlay={true}
+    preload={true}
+/>
+```
+
+The bulk of the properties that are exposed are directly from the [`asciinema-player`](https://github.com/asciinema/asciinema-player) component - this page has a more detailed description of many of the properties listed below. The following properties are exposed:
+
+| Property         | Usage                                                                             |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `src` | The location of the cast file, must be available from the browser. |
+| `style` | Any additional CSS styles to apply. |
+| `cols` | The number of columns in the player's terminal. |
+| `rows` | The number of rows in the player's terminal. |
+| `autoPlay` |  Set this option to `true` if playback should start automatically. |
+| `preload` | Set this option to `true` if the recording should be preloaded on player's initialization. |
+| `loop` | Set this option to either true or a number if playback should be looped. When set to a number (e.g. 3) then the recording will be re-played given number of times and stopped after that. |
+| `startAt` |  Start playback at a given time. |
+| `speed` |  Playback speed. The value of 2 means 2x faster. |
+| `idleTimeLimit` | Limit terminal inactivity to a given number of seconds. |
+| `theme` | Terminal color theme. |
+| `poster` | Poster (a preview frame) to display until the playback is started. |
+| `fit` | Controls the player's fitting (sizing) behaviour inside its container element. |
+| `fontSize` | Size of the terminal font. |
+
+## AnnotatedCommand
+
+The `AnnotatedCommand` component is used to create a set of keystrokes, for example for Vim, with a small text annotation beneath. This is useful in Markdown tables showing how Vim commands work, as multiline text in tables is a bit fiddly to work with.
+
+First, import the component:
+
+```jsx
+import AnnotatedCommand from '@site/src/components/AnnotatedCommand/AnnotatedCommand.tsc';
+```
+
+Use the component as below:
+
+```jsx live
+<AnnotatedCommand
+  annotation="Go to beginning of buffer, change two words"
+>gg2cw</AnnotatedCommand>
+```
+
+The following properties are exposed:
+
+| Property         | Usage                                                                             |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `annotation`           | The text to show beneath the command. |
+
+## Caret
+
+The `Caret` component is useful when showing Vim or Terminal samples where you need to indicate the position of the caret. It can show a block caret, which is the standard for an ASCII terminal, or a line caret, which can be used in things like iTerm to indicate Insert Mode for Vim.
+
+First, import the component:
+
+```jsx
+import Caret from '@site/src/components/Caret/Caret.tsx';
+```
+
+Use the component as below:
+
+```jsx live
+<code className="language-python">
+    def search_for_word<Caret caretStyle='block'>(</Caret>word):
+</code>
+```
+
+The following properties are exposed:
+
+| Property         | Usage                                                                             |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `caretStyle`           | The style of the cursor, `block` by default, or `line` for an 'insert mode' cursor. |
+
+## Tips for Developing Components
+
+Check the following resources for useful tips on Component Development:
+
+- [Docusaurus - Styling and Layout](https://docusaurus.io/docs/styling-layout)
+- [Docusaurus - Code Blocks - Interactive code editor](https://docusaurus.io/docs/markdown-features/code-blocks#interactive-code-editor)

docs/zz-developer-guide/images-and-diagrams.mdx

@@ -0,0 +1,38 @@
+---
+title: Images and Diagrams
+---
+
+import Image from '@theme/IdealImage';
+import Drawio from '@theme/Drawio'
+
+## Images
+
+The [`@docusaurus/plugin-ideal-image`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-ideal-image) is used to allow lazy loading and zoom of images.
+
+Use the `Image` tag as shown:
+
+```markdown
+import Image from '@theme/IdealImage';
+<Image img={require('./images/vim-cheatsheet.png')} />
+```
+
+This will render an image as shown below:
+
+<Image img={require('./images/vim-cheatsheet.png')} />
+
+## Diagrams
+
+Render a Draw.io diagram like so:
+
+```
+import Drawio from '@theme/Drawio'
+import asymmetricEncryption from '!!raw-loader!./images/asymmetric-encryption.drawio';
+
+<Drawio content={asymmetricEncryption} />
+```
+
+This would render as below:
+
+import asymmetricEncryption from '!!raw-loader!./images/asymmetric-encryption.drawio';
+
+<Drawio content={asymmetricEncryption} />

docs/zz-developer-guide/images/asymmetric-encryption.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-04-05T05:58:06.492Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.4.0 Chrome/91.0.4472.164 Electron/13.5.0 Safari/537.36" etag="WB49tPhE24BtVEzryK7K" version="15.4.0" type="device"><diagram id="zMdPa7TFIofes7aEGqtK" name="Page-1">3VfbUtswEP2aPJKRrTikj+QC7RQGpulM26eOYiu2GtvryjKJ+fqubPmGk0A7gYHygnS02mjP2V1LAzqLdleSJcENeDwc2MTbDeh8YNuWRcb4TyN5iUzsSQn4UnjGqAGW4oEbkBg0Ex5PO4YKIFQi6YIuxDF3VQdjUsK2a7aGsPurCfN5D1i6LOyj34Sngiqu8Ydm4SMXfqCq+M7LhYhVxiaSNGAebFsQXQzoTAKochTtZjzU5FW8lPsuD6zWB5M8Vs/Z8EV+yleLW0c6V78p8ZQD/OeZieKehZkJ+E6Ke6b4wB6H6Ha6kjjy9egzz00gKq/YwZgSPYwBd9DpNhCKLxPmamyLCYFYoKIQZ5b2xdyNLyGLvdtMhSLmBveY3NziLqF0kpAhcRA0B+NS8d3BiK2aR0xADhFXEg9Jqg0jQ73JPWqNyvm2UXJiTIKWhhYxIDPJ49euG35xYCj+C7qdHoPcw3QzU5AqAB9iFi4adFoQxrVXgrPG5hogMQT+4krlpnZYpqBLO7Il8+9mfzH5UdDsVNP5rr04z82sPKs+4HH+MR7IpMuPxF1VLpM+V0fs6H49JQ+ZEvfdc5xcnHGvFpY89hBZxK7ME8X1+IanqW4Z+3S8Zivsfh3uWSj8GMcuUsYlAjqhBbaXC7MQCc8rZeapeGCrwp9mPwERqyJEZzpw5scqwvQ+s7npOG2lDqfjwfI5I0OLTGjp69kSGHd3+vitUqTdHbBep5gJjyWrD/HvKlo9FY18bfGwA2ADsEnd7Mi+7tatvCeaW6obWOx/LYqSNMA1X6suMgWlIOpiODtV07O7Tc+ummCr6dU27a43fqmmZ/cUweR3+yVUfUyyKLxwFbSrpaisO0iFEqCrZmUo7JWTgkeyQPmlmdXXA3IimsdOh2ZrD830NVmmPZbn/HDeZyuU4H9K+9HkraX9qCfIFFbvO+kd+40l/aTHcY/gFi1PEtv7WofaclpfW2cQaoXQLV0XfwfFSJWETf1isGuk5YGQCbksaqF6GJDiLpwGde1VyRHtfP26GgpIz4cCP/fpMAR3o+1Oc08edWSl1nlPVnvUl5W+lKzV46/9LDEd6/2/Shzyeq8SnDYPzPKG1TzT6eIP</diagram></mxfile>

docusaurus.config.js

@@ -55,6 +55,11 @@ const config = {
             require.resolve('react-mailchimp-email-signup-form/dist/esm/index.css'),
             require.resolve('asciinema-player/dist/bundle/asciinema-player.css'),
           ],
+
+          //  Add theming support for languages we use.
+          prism: {
+            additionalLanguages: [],
+          },
         },
         gtag: {
           trackingID: 'G-8HZFMZV9Z4',
@@ -124,6 +129,16 @@ const config = {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
       },
+      liveCodeBlock: {
+        /**
+         * The position of the live playground, above or under the editor
+         * Possible values: "top" | "bottom"
+         * We use 'top' as we are currently using this editor to preview
+         * components, and we want to show the rendered component before its
+         * code (see 'Developer Guide > Components').
+         */
+        playgroundPosition: 'top',
+      },
     }),
 
   plugins: [
@@ -137,6 +152,17 @@ const config = {
       require.resolve('docusaurus-plugin-drawio'),
       {}
     ],
+    [
+      require.resolve('@docusaurus/theme-live-codeblock'),
+      {}
+    ],
+    [
+      require.resolve('@docusaurus/plugin-ideal-image'),
+      {
+        //  Enable this plugin in dev so that we can test it.
+        disableInDev: false,
+      },
+    ],
   ],
 };