refactor: complete the refactor to docusaurus

.github/contributing.md

@@ -3,8 +3,3 @@
 ❗ Important ❗
 
 Content in this repository may be published as a physical book. Please be aware that any contributions may be used commercially. I will try to keep track of contributors and attribute them in any printed material, but cannot make any guarantees on this, and therefore please assume that any contributions waive all rights to copyright etc.
-
-## Style Guide
-
-Please check the [Style Guide](./style-guide.md) for detailed notes on the preferred style of the book.
-

.github/workflows/release-please.yaml

@@ -43,5 +43,5 @@ jobs:
         uses: JamesIves/[email protected]
         with:
           branch: gh-pages
-          folder: ./website/public
+          folder: ./build
         if: ${{ steps.release.outputs.release_created }}

.gitignore

@@ -9,3 +9,28 @@ artifacts/
 .idea/
 .DS_Store
 statistics.csv
+
+# Docusaurus ignores
+
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# End of Docusaurus ignores

README.md

@@ -44,17 +44,15 @@ The one-line shell installer is hosted at [github.com/dwmkerr/effective-shell-in
 
 ## The Website
 
-The content in this repository is built into a static site available at [effective-shell.com](https://effective-shell.com). This is done using [Hugo](https://gohugo.io/).
+The content in this repository is built into a static site available at [effective-shell.com](https://effective-shell.com). This site is generated using [Docusaurus](https://docusaurus.io).
 
 This section contains information on how to built, use and edit the site. To help you quickly edit the site, some tips are below:
 
-- The main _content_ is at [website/content/docs/](website/content/docs/)
-- The menu structure is defined at [website/content/menu/index.md](website/content/menu/index.md).
+- The book content is at [./docs/](./docs/)
+- The menu structure is defined at [sidebars.js](sidebars.js).
 
 ### Building the Website
 
-This website is built with [Hugo](https://gohugo.io/). It is very easy to setup and run locally.
-
 To setup dependencies, run:
 
 ```sh
@@ -149,19 +147,19 @@ This is a short-and-sweet task list for the refactoring process.
 - [x] Deploy
 - [x] Test deployment
 - [x] Fix hints
-- [ ] Part 2, migrate and preview
-- [ ] Part 3, migrate and preview
-- [ ] Part 4, migrate and preview
-- [ ] Part 5, migrate and preview
-- [ ] Part 6, migrate and preview
-- [ ] Create a really nice animation: https://starship.rs/ also look at a yes no question, 'become a shell expert' or something
-- [ ] Fixup table of contents
-- [ ] Fixup appendix/todo/missing chapters
-- [ ] Fix relref links
-- [ ] Fix TODOs
-- [ ] Test grep styling and relrefs
-- [ ] Ensure that google analytics integration is working.
-- [ ] Replace `version.txt` to `package.json`
+- [x] Part 2, migrate and preview
+- [x] Part 3, migrate and preview
+- [x] Part 4, migrate and preview
+- [x] Part 5, migrate and preview
+- [x] Part 6, migrate and preview
+- [x] Create a really nice animation: https://starship.rs/ also look at a yes no question, 'become a shell expert' or something
+- [x] Fixup table of contents
+- [x] Fixup appendix/todo/missing chapters
+- [x] Fix relref links
+- [x] Fix TODOs
+- [x] Test grep styling and relrefs
+- [x] Ensure that google analytics integration is working.
+- [x] Replace `version.txt` to `package.json`
 - [ ] Remove old files
 - [ ] Build
 - [ ] Deploy

effective-shell/docs/01-transitioning-to-the-shell/02-navigating-your-system/index.md → docs/01-transitioning-to-the-shell/02-navigating-your-system/index.md

@@ -23,7 +23,7 @@ You should see something like this:
 
 When we open a folder in a graphical user interface, we are always viewing the contents of a folder, or directory. When you open the shell, the same applies - we are always sitting in a specific directory.
 
-The `pwd` command is the _Print Working Directory_ command. It shows the full path of the directory that you are in. You might not use this command very often, as in many shells you can see the directory you are in (if you cannot see this in your shell, you'll find out how to do this in [Chapter 18](#TODO)).
+The `pwd` command is the _Print Working Directory_ command. It shows the full path of the directory that you are in.
 
 There's one more way to find the working directory. It is stored in an _Environment Variable_ called `PWD`.
 
@@ -55,7 +55,7 @@ You should see something like this:
 
 The `ls` command is the _List Directory Contents_ command. It will show the contents of a directory. If we don't give it any parameters, it will show the contents of the current directory.
 
-There are a lot of options for the `ls` command. In [Chapter 5](#TODO) we'll see how to find out the options for commands. For now, let's look at one of the most common options `-l`. This shows the contents as a list:
+There are a lot of options for the `ls` command. For now, let's look at one of the most common options `-l`. This shows the contents as a list:
 
 ```bash
 ls -l

effective-shell/docs/01-transitioning-to-the-shell/05-getting-help/index.md → docs/01-transitioning-to-the-shell/05-getting-help/index.md

@@ -118,7 +118,7 @@ cd: cd [-L|[-P [-e]] [-@]] [dir]
 # (I've skipped the bulk of the output to save space!)
 ```
 
-This is all I'll say about `help` for now. We visit it again in [Chapter 10 - Understanding Commands](../../02-core-skills/10-understanding-commands/index'), where we talk more about built-in commands. For now we'll go back to the `man` command, which works across all shells as it is a Linux feature rather than a shell specific feature!
+This is all I'll say about `help` for now. We visit it again in [Chapter 10 - Understanding Commands](../../02-core-skills/10-understanding-commands/index.md), where we talk more about built-in commands. For now we'll go back to the `man` command, which works across all shells as it is a Linux feature rather than a shell specific feature!
 
 ### Manual Sections
 

effective-shell/docs/02-core-skills/07-thinking-in-pipelines/index.md → docs/02-core-skills/07-thinking-in-pipelines/index.md

@@ -69,7 +69,7 @@ lr-xr-xr-x 1 root wheel 0 Jan  1  1970 /dev/stdin -> fd/0
 lr-xr-xr-x 1 root wheel 0 Jan  1  1970 /dev/stdout -> fd/1
 ```
 
-If you are not familiar with `ls` (the _list directory contents_ command) then check [Chapter 2 - Navigating Your System](../../part-1-transitioning-to-the-shell/navigating-your-system'). The first part of the output isn't too important - but we can see we have three files in the special `/dev/` (short for _device_ folder). We can also see the associated file descriptors.
+If you are not familiar with `ls` (the _list directory contents_ command) then check [Chapter 2 - Navigating Your System](../../01-transitioning-to-the-shell/02-navigating-your-system/index.md). The first part of the output isn't too important - but we can see we have three files in the special `/dev/` (short for _device_ folder). We can also see the associated file descriptors.
 
 As an aside - this is a really fundamental thing we'll see again and again in Unix and Linux - almost everything can be represented as a file. This is a core concept and one we'll touch on regularly.
 
@@ -105,7 +105,7 @@ Agnes Skinner
 Helen Lovejoy
 ```
 
-We saw in [Chapter 4 - Becoming a Clipboard Gymnast](../../part-1-transitioning-to-the-shell/clipboard-gymnastics') that we could **pipe** the output of this command into the `sort` command to order it and then into the `uniq` command to remove duplicates, like this:
+We saw in [Chapter 4 - Becoming a Clipboard Gymnast](../../01-transitioning-to-the-shell/04-clipboard-gymnastics/index.md) that we could **pipe** the output of this command into the `sort` command to order it and then into the `uniq` command to remove duplicates, like this:
 
 ```
 $ cat ~/effective-shell/text/simpsons-characters.txt | sort | uniq
@@ -188,7 +188,7 @@ The `<` operator redirects the standard input of a program to come from the give
 
 **The Clipboard**
 
-In [Chapter 4 - Becoming a Clipboard Gymnast](../../part-1-transitioning-to-the-shell/clipboard-gymnastics') we saw a trick to remove formatting from text in the clipboard. Here's a similar trick to reverse the contents of the clipboard:
+In [Chapter 4 - Becoming a Clipboard Gymnast](../../01-transitioning-to-the-shell/04-clipboard-gymnastics/index.md) we saw a trick to remove formatting from text in the clipboard. Here's a similar trick to reverse the contents of the clipboard:
 
 ```
 $ pbpaste | rev | pbcopy
@@ -246,7 +246,7 @@ You'll see something like this:
 
 This long list of files would be hard to search through if it was printed directly to the shell, but in the pager we can use the `d` and `u` keys to go _down_ and _up_, or the `/` and `?` keys to search forwards or backwards.
 
-Piping into your pager is a really useful trick - you can read more about pagers in [Chapter 5 - Getting Help](../../part-1-transitioning-to-the-shell/getting-help).
+Piping into your pager is a really useful trick - you can read more about pagers in [Chapter 5 - Getting Help](../../01-transitioning-to-the-shell/05-getting-help/index.md).
 
 **File**
 
@@ -539,7 +539,7 @@ There are a few chapters which are planned to come later which go into detail on
 When these chapters are published I'll update the links here. If you want to be updated when new chapters are published, you can [Join the Mailing Lits on the Homepage](https://effective-shell.com).
 
 [^1]: Technically there is another layer here, which is the `tty`. You can see this by running `tty` in the shell. We'll more about this in the [Interlude - What is a Shell](#TODO) section.
-[^2]: Check [Chapter 4 - Becoming a Clipboard Gymnast](../../part-1-transitioning-to-the-shell/clipboard-gymnastics) for how to do this on a Linux or Windows machine.
+[^2]: Check [Chapter 4 - Becoming a Clipboard Gymnast](../../01-transitioning-to-the-shell/04-clipboard-gymnastics/index.md) for how to do this on a Linux or Windows machine.
 [^3]: Although always use tricks like this with caution! If we had a _different_ error, perhaps one we really do want to know about, we would lose the message in this case.
 [^4]: There is a very detailed explanation of this behaviour at https://linuxnewbieguide.org/21-and-understanding-other-shell-scripts-idioms/.
 [^5]: With the correct options, `sed` could likely do this in a single operation, but I'd probably spend a lot longer Googling the right options for it!

effective-shell/docs/02-core-skills/09-job-control/index.md → docs/02-core-skills/09-job-control/index.md

@@ -81,7 +81,7 @@ We have a problem. The `python` process is still running - it's serving the webs
 
 In the example above, I try to run `vi`, but nothing is happening. Standard input is not being read by the server and not being interpreted by the shell.
 
-I have to kill the server by hitting `Ctrl+C`. This sends a `SIGINT` signal (which tells the command to stop). We saw signals briefly in [Chapter 4 - Becoming a Clipboard Gymnast](../../01-transitioning-to-the-shell/04-clipboard-gymnastics) and we'll see more of them in as we continue. Now I need to clear my screen to get rid of all of the error messages, then start again.
+I have to kill the server by hitting `Ctrl+C`. This sends a `SIGINT` signal (which tells the command to stop). We saw signals briefly in [Chapter 4 - Becoming a Clipboard Gymnast](../../01-transitioning-to-the-shell/04-clipboard-gymnastics/index.md) and we'll see more of them in as we continue. Now I need to clear my screen to get rid of all of the error messages, then start again.
 
 This is obviously not optimal. Let's look at some solutions.
 
@@ -276,7 +276,7 @@ If you want to find out more about the gory details of jobs, the best place to s
 
 [^1]: If you are not a heavy shell user, this might seem unlikely. But if you do a lot of work in shells, such as sysadmin, devops, or do your coding from a terminal, this happens all the time!
 
-[^3]: Technically, `SIGTSTP` signal - which is 'TTY stop'. If you have always wondered about the 'TTY' acronym, check the chapter, [Interlude: Understanding the Shell](TODO).
+[^3]: Technically, `SIGTSTP` signal - which is 'TTY stop'. If you have always wondered about the 'TTY' acronym, check the chapter, [Interlude: Understanding the Shell](../../02-core-skills/10-understanding-commands/index.md).
 
 [^4]: The alternative method is to use `Ctrl+Y`, which will send a _delayed interrupt_, which will continue to run the process until it tries to read from `stdin`. At this point, the job is suspended and the control given to the shell. The operator can then use `bg` or `kill` or `fg` to either move to the background, stop the process, or keep in the foreground as preferred. See: https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Job-Control
 

effective-shell/docs/02-core-skills/10-understanding-commands/index.md → docs/02-core-skills/10-understanding-commands/index.md

@@ -164,7 +164,7 @@ Builtins will vary from shell to shell, but many shells are 'Bash-like' - meanin
 
 https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html
 
-As should be familiar from [Chapter 5 - Getting Help](../../part-2-core-skills/05-getting-help), you can get help for builtins:
+As should be familiar from [Chapter 5 - Getting Help](../../01-transitioning-to-the-shell/05-getting-help/index.md), you can get help for builtins:
 
 ```bash
 $ man source     # source is a builtin

effective-shell/docs/02-core-skills/12-what-is-a-shell/index.md → docs/02-core-skills/12-what-is-a-shell/index.md

@@ -143,9 +143,9 @@ Shells can write output to files or other locations, and so on. You can run a sh
 
 So what else does a shell do? Most of the features are related to helping human operators work with the system more efficiently.
 
-- Quickly enter commands, see the history of commands and quickly restructure commands (see [Chapter 8 - Fly on the Command Line](../../part-2-core-skills/fly-on-the-command-line))
-- Navigate through the file system, moving from folder to folder (see [Chapter 1- Navigating Your System](../../part-1-transitioning-to-the-shell/navigating-your-system)), which makes it easier for an operator to navigate the file system
-- Chain the output of commands together - for example, taking the output of one basic program, such as the `tree` program we saw, and writing it to a file (see [Chapter 7 - Thinking in Pipelines](../../part-2-core-skills/thinking-in-pipelines))
+- Quickly enter commands, see the history of commands and quickly restructure commands (see [Chapter 8 - Fly on the Command Line](../../02-core-skills/08-fly-on-the-command-line/index.md))
+- Navigate through the file system, moving from folder to folder (see [Chapter 1- Navigating Your System](../../01-transitioning-to-the-shell/02-navigating-your-system/index.md)), which makes it easier for an operator to navigate the file system
+- Chain the output of commands together - for example, taking the output of one basic program, such as the `tree` program we saw, and writing it to a file (see [Chapter 7 - Thinking in Pipelines](../../02-core-skills/07-thinking-in-pipelines/index.md))
 - Offer a programming language, allowing the operator to perform more complicated tasks
 
 And a lot more! In fact, that's what the whole book is about - how to get the most from these powerful programs, particularly for those who use them regularly.
@@ -172,7 +172,7 @@ Shell command prompts can be customised, so they will often look different from
 
 A lot of the 'commands' in a shell, such as `cat` (which shows the contents of a file), are actually just simple programs, which will interface with the kernel. No matter what shell you use, these commands will behave the same way, because really all you are doing is calling another program.
 
-Some commands, such as `cd` (change directory), are built into the shell. Some commands are functions that have been defined, or aliases to other commands (for more details on commands, see [Chapter 10 - Understanding Commands](../../part-2-core-skills/understanding-commands)). Commands will often differ between shells.
+Some commands, such as `cd` (change directory), are built into the shell. Some commands are functions that have been defined, or aliases to other commands (for more details on commands, see [Chapter 10 - Understanding Commands](../../02-core-skills/10-understanding-commands/index.md)). Commands will often differ between shells.
 
 Not all shells are created equal - anyone can write a shell program, maybe creating a simple interface to the computer or a highly complex one with many features. In fact, a later article in this series will look at the genealogy of the most common shells.
 

effective-shell/docs/03-manipulating-text/14-get-to-grips-with-grep/index.md → docs/03-manipulating-text/14-get-to-grips-with-grep/index.md

@@ -45,7 +45,7 @@ $ tldr grep
   Supports simple patterns and regular expressions.
 ```
 
-That is indeed a little more concise. By the way, if you are not familiar with how you can get help on commands, check out [Chapter 5 - Getting Help](../../part-1-transitioning-to-the-shell/getting-help). As the manual pages indicate, `grep` is used to match patterns in files. More advanced users will most likely know exactly what this means, but a more simple description is just:
+That is indeed a little more concise. By the way, if you are not familiar with how you can get help on commands, check out [Chapter 5 - Getting Help](../../01-transitioning-to-the-shell/05-getting-help/index.md). As the manual pages indicate, `grep` is used to match patterns in files. More advanced users will most likely know exactly what this means, but a more simple description is just:
 
 > Grep lets you search for text or filter text.
 
@@ -69,7 +69,7 @@ You can read more about this story and some of the fascinating history of the ea
 
 ## Searching Through Text
 
-If you've been working through this book, you've probably entered quite a few commands in the shell. Most shells keep a history of the commands you type. Under the hood, when you use the up and down keys to look through commands you entered earlier, or use the `Ctrl-R` shortcut to _search_ through earlier commands, your shell is looking through this file. If these tricks are not familiar, check [Chapter 9 - Fly on the Command Line](../../part-2-core-skills/fly-on-the-command-line).
+If you've been working through this book, you've probably entered quite a few commands in the shell. Most shells keep a history of the commands you type. Under the hood, when you use the up and down keys to look through commands you entered earlier, or use the `Ctrl-R` shortcut to _search_ through earlier commands, your shell is looking through this file. If these tricks are not familiar, check [Chapter 9 - Fly on the Command Line](../../02-core-skills/08-fly-on-the-command-line/index.md).
 
 The file which keeps the history can vary from shell to shell. For example, on my system, my history for Bash is in the file `~/.bash_history`. But most 'Bash-like' shells provide a built-in environment variable which let's you find the path of the shell history. Let's at this file:
 
@@ -103,7 +103,7 @@ nvim perfor<strong>man</strong>ce.md{'\n'}
 
 Here I can see all of the commands I have recently entered which have the text `man` in them. Note that the text which matches is highlighted and shown in bold.
 
-Now what if you a different shell, or forget where the history file lives? A nice trick here is to use the `history` command. This command prints out the history, as well as the line number. The `history` command writes to `stdout`. If we don't give `grep` a source file, it will simply search through `stdin`. Just as we learnt in [Chapter 7 - Thinking in Pipelines](../../part-2-core-skills/thinking-in-pipelines) this means we can just `grep` the output of the `history` command!
+Now what if you a different shell, or forget where the history file lives? A nice trick here is to use the `history` command. This command prints out the history, as well as the line number. The `history` command writes to `stdout`. If we don't give `grep` a source file, it will simply search through `stdin`. Just as we learnt in [Chapter 7 - Thinking in Pipelines](../../02-core-skills/07-thinking-in-pipelines/index.md) this means we can just `grep` the output of the `history` command!
 
 Here's how that would work: