diff --git a/.gitignore b/.gitignore
index 4d62ae56..1d835554 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,11 @@
# Created by https://www.toptal.com/developers/gitignore/api/yarn,node,docusaurus,visualstudiocode,webstorm
# Edit at https://www.toptal.com/developers/gitignore?templates=yarn,node,docusaurus,visualstudiocode,webstorm
+### ir-docs ###
+
+# symlink backup directory
+tmp/symlink/**/*
+
### Docusaurus ###
# Docusaurus cache and generated files
.docusaurus
@@ -371,3 +376,5 @@ fabric.properties
# End of https://www.toptal.com/developers/gitignore/api/yarn,node,docusaurus,visualstudiocode,webstorm
.DS_Store
+/.idea/git_toolbox_prj.xml
+/.idea/vcs.xml
diff --git a/.idea/jsLibraryMappings.xml b/.idea/jsLibraryMappings.xml
deleted file mode 100644
index d23208fb..00000000
--- a/.idea/jsLibraryMappings.xml
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/jsonSchemas.xml b/.idea/jsonSchemas.xml
deleted file mode 100644
index 573d6451..00000000
--- a/.idea/jsonSchemas.xml
+++ /dev/null
@@ -1,27 +0,0 @@
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/vcs.xml b/.idea/vcs.xml
deleted file mode 100644
index 7ddfc9ed..00000000
--- a/.idea/vcs.xml
+++ /dev/null
@@ -1,12 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/yamllint.xml b/.idea/yamllint.xml
deleted file mode 100644
index 735a954d..00000000
--- a/.idea/yamllint.xml
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-
- true
- /opt/homebrew/bin/yamllint
-
-
\ No newline at end of file
diff --git a/README.md b/README.md
index b6ec5950..6e72156b 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,7 @@ ir-docs is a single instance of Docusaurus that fetches and builds the `/docs` f
For example, Gluegun's docs live at `https://github.com/infinitered/gluegun/tree/master/docs`. When new docs are pushed to `master`, Gluegun's Circle CI triggers a build action that then prompts ir-docs to publish those docs at `docs.infinite.red/gluegun`.
-> ⚠️⚠️ **IMPORTANT NOTE** ⚠️⚠️
->
+> [!Caution]
> DO NOT EDIT THE `./docs` DIRECTORY IN THIS REPOSITORY!
>
> **Edits to documentation for a particular project should be made in that project's repository!**
@@ -23,21 +22,37 @@ To see how your docs will look on `docs.infinite.red` before publishing them, yo
git clone git@github.com:infinitered/ir-docs.git ~/ir-docs
```
-2. Symlink your project's docs folder into the `ir-docs/docs` folder.
+2. Use the symlink script to link your projects docs folder into the `ir-docs/docs` folder.
+```bash
+yarn symlink add [project_name] [path_to_directory]
```
-ln -s ~/my-project/docs ~/ir-docs/docs/my-project
-```
+
+For instance to link the ignite docs you might do `yarn symlink add ignite-cli ../ignite/docs`.
+
+This will:
+ 1. Backup the contents of `./docs/ignite-cli` to `./tmp/symlink/ignite-cli`
+ 2. Create a symlink at `./docs/ignite-cli` that points to `../ignite/docs`
+ 3. Create a `_category.json_` file in `./docs/ignite-cli` with the correct project name
+
+> [!Note]
+> Remember not to commit any changes to the `./docs` folder manually.
3, Run the docusaurus dev server
-```
-cd ~/ir-docs
-yarn start
-```
-The preview should open automatically at `http://localhost:3000`
+ ```
+ cd ~/ir-docs
+ yarn start
+ ```
+ The preview should open automatically at `http://localhost:3000`
4. Edit your project's docs in place and the changes should hot reload in the browser!
+5. Restore the original folder
+ You can use the restore script to remove the symlink and restore the original files:
+ ```shell
+ yarn symlink remove [project-name]
+ ```
+
## Preparing your project for `ir-docs`
To prepare your project for `ir-docs` you'll need to do the following:
diff --git a/package.json b/package.json
index 542524f5..3b008881 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,8 @@
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids",
- "typecheck": "tsc"
+ "typecheck": "tsc",
+ "symlink": "bash ./scripts/symlink.sh"
},
"dependencies": {
"@docusaurus/core": "2.4.3",
@@ -51,6 +52,6 @@
]
},
"engines": {
- "node": ">=16.14"
+ "node": ">=18.19"
}
}
diff --git a/scripts/symlink.sh b/scripts/symlink.sh
new file mode 100644
index 00000000..4bdebda9
--- /dev/null
+++ b/scripts/symlink.sh
@@ -0,0 +1,190 @@
+#!/bin/bash
+
+# Define function to create _category_.json
+CreateCategoryJSON() {
+ PROJECT_NAME=$1
+ DOCS_DIR="./docs"
+
+ # Ensure the target directory exists
+ mkdir -p "$DOCS_DIR/$PROJECT_NAME/"
+
+ # Inlined template with placeholders
+ TEMPLATE='{
+ "label": "'"${PROJECT_NAME}"'",
+ "link": null,
+ "customProps": {
+ "description": "",
+ "projectName": "'"${PROJECT_NAME}"'",
+ "sidebar": {
+ "type": "autogenerated",
+ "dirName": "'"${PROJECT_NAME}"'"
+ }
+ }
+}'
+
+ # Print the JSON to the _category_.json file
+ echo "$TEMPLATE" > "$DOCS_DIR/$PROJECT_NAME/_category_.json"
+
+ echo "$(tput setaf 2)_category_.json file created successfully.$(tput sgr 0)"
+}
+
+LinkStaticDocs() {
+ TARGET_REPO_DIRECTORY=$1
+ PROJECT_NAME=$2
+ # Link static content out of /docs into /static.
+ echo "Checking for static files in the target repository."
+ if [ -d "$TARGET_REPO_DIRECTORY/docs/$PROJECT_NAME/_static_" ]; then
+ echo "Creating links for static files." >&2
+
+ # Ensure the target directory exists
+ mkdir -p "$TARGET_REPO_DIRECTORY/static/$PROJECT_NAME"
+
+ # Iterate over files and create symbolic links
+ find "$TARGET_REPO_DIRECTORY/docs/$PROJECT_NAME/_static_" -type f -exec ln -s {} "$TARGET_REPO_DIRECTORY/static/$PROJECT_NAME/" \;
+
+ echo "Links for static files created successfully." >&2
+ else
+ echo "No static files to link." >&2
+ fi
+}
+
+ACTION=$1
+
+if [ -z "$ACTION" ] || [ "$ACTION" = "--help" ]; then
+ echo -e "$(tput setaf 4)IR-DOCS SYMLINKING TOOL$(tput sgr 0)\n"\
+ "Creates and removes symlinks for local testing\n\n"\
+ "$(tput setaf 1)USAGE:$(tput sgr 0)\n"\
+ " To create a symlink:\n\n"\
+ " > $(tput bold)$(tput setaf 3)yarn symlink add [project_name] [path_to_directory]$(tput sgr 0)\n\n"\
+ " This will create a symlink at ./docs/[project_name] that points to [path_to_directory].\n"\
+ " The existing directory at ./docs/[project_name] will be moved to $(tput setaf 3)tmp/symlink/[project_name]$(tput sgr 0).\n"\
+ " In addition, a $(tput setaf 3)_category_.json$(tput sgr 0) file will be created in the ./docs/[project_name] directory.\n\n"\
+ " To remove a symlink:\n\n"\
+ " > $(tput bold)$(tput setaf 3)yarn symlink remove [project_name]$(tput sgr 0)\n\n"\
+ " This removes the symlink and restores the backup at tmp/symlink/[project_name], if available."
+ exit 0
+fi
+
+if [ "$ACTION" = "add" ]; then
+ # Ensure two arguments are provided
+ if [ "$#" -ne 3 ]; then
+ echo "$(tput setaf 1)Error: The add command requires two arguments:[project_name] [path_to_directory].$(tput sgr 0)"
+ exit 1
+ fi
+
+ PROJECT_NAME=$2
+ SOURCE_DIR=$3
+ DOCS_DIR="$PWD/docs"
+ TARGET="$DOCS_DIR/$PROJECT_NAME"
+ STATIC_DIR="$PWD/static"
+ TARGET_STATIC="$STATIC_DIR/$PROJECT_NAME"
+ BACKUP_DIR="./tmp/symlink"
+ BACKUP_DOCS_DIR="$BACKUP_DIR/docs"
+ BACKUP_STATIC_DIR="$BACKUP_DIR/static"
+
+ # Get the absolute path of the directory
+ ABSOLUTE_SOURCE_DIR=$(realpath "$SOURCE_DIR")
+ SOURCE_STATIC_DIR="$ABSOLUTE_SOURCE_DIR/_static_"
+
+ # Check if target already is a symlink
+ if [ -h $TARGET ]; then
+ echo "$(tput setaf 3)$TARGET is already a symlink. Aborting...$(tput sgr 0)"
+ exit 1
+ fi
+
+ # If a directory already exists at the target
+ if [ -d "$TARGET" ]; then
+ # Backup the existing directory by moving it
+ echo "$(tput setaf 3)Saving backup of existing directory in $BACKUP_DOCS_DIR/$(tput sgr 0)"
+ mkdir -p "$BACKUP_DOCS_DIR"
+ mv "$TARGET" "$BACKUP_DOCS_DIR"
+ fi
+
+ if [ -d "$TARGET_STATIC" ]; then
+ # Backup the existing static files by moving them
+ echo "$(tput setaf 3)Saving backup of existing static directory in $BACKUP_STATIC_DIR$(tput sgr 0)"
+ mkdir -p "$BACKUP_STATIC_DIR"
+ mv "$TARGET_STATIC" "$BACKUP_STATIC_DIR"
+ fi
+
+ # Create symlink
+ echo "$(tput setaf 3)Creating symlink... $TARGET --> $ABSOLUTE_SOURCE_DIR $(tput sgr 0)"
+ ln -s "$ABSOLUTE_SOURCE_DIR" "$TARGET"
+ if [ -d "$SOURCE_STATIC_DIR" ]; then
+ echo "$(tput setaf 3)Creating symlink... $TARGET_STATIC --> $ABSOLUTE_SOURCE_DIR/_static_ $(tput sgr 0)"
+ ln -s "$SOURCE_STATIC_DIR" "$TARGET_STATIC"
+ else
+ echo "No static files in $SOURCE_STATIC_DIR"
+ fi
+
+ # Call function to create _category_.json
+ CreateCategoryJSON "$PROJECT_NAME"
+
+
+elif [ "$ACTION" = "remove" ]; then
+ # Ensure one argument is provided
+ if [ "$#" -ne 2 ]; then
+ echo "$(tput setaf 1)Error: The remove command requires one argument: [project_name].$(tput sgr 0)"
+ exit 1
+ fi
+
+ PROJECT_NAME=$2
+ DOCS_DIR="./docs"
+ TARGET="$DOCS_DIR/$PROJECT_NAME"
+ STATIC_DIR="./static"
+ TARGET_STATIC="$STATIC_DIR/$PROJECT_NAME"
+ BACKUP_DIR="./tmp/symlink"
+ BACKUP_DOCS_DIR="$BACKUP_DIR/docs"
+ BACKUP_STATIC_DIR="$BACKUP_DIR/static"
+
+ if [ ! -L $TARGET ]; then
+ echo "$(tput setaf 3)$TARGET is not a symlink. Aborting...$(tput sgr 0)"
+ exit 1
+ fi
+
+ # Remove symlink
+ echo "$(tput setaf 3)Removing symlinks...$(tput sgr 0)"
+ rm -r "$TARGET"
+
+ if [ -L $TARGET_STATIC ]; then
+ rm -r "$TARGET_STATIC"
+ fi
+
+ # If backup docs exist
+ if [ -d "$BACKUP_DOCS_DIR/$PROJECT_NAME" ]; then
+ # Restore the directory
+ echo "$(tput setaf 3)Restoring docs backup...$(tput sgr 0)"
+ mv "$BACKUP_DOCS_DIR/$PROJECT_NAME" "$DOCS_DIR"
+
+ # Check if the backup directory is empty and remove it if so
+ if [ -z "$(ls -A -- "$BACKUP_DOCS_DIR")" ]; then
+ rmdir "$BACKUP_DOCS_DIR"
+ fi
+ fi
+
+ # If backup static files exist
+ if [ -d "$BACKUP_STATIC_DIR/$PROJECT_NAME" ]; then
+ # Restore the static files
+ echo "$(tput setaf 3)Restoring static backup...$(tput sgr 0)"
+ mv "$BACKUP_STATIC_DIR/$PROJECT_NAME" "$STATIC_DIR"
+
+ # Check if the backup directory is empty and remove it if so
+ if [ -z "$(ls -A -- "$BACKUP_STATIC_DIR")" ]; then
+ rmdir "$BACKUP_STATIC_DIR"
+ fi
+ fi
+
+ if [ -z "$(ls -A -- "$BACKUP_DIR")" ]; then
+ rmdir "$BACKUP_DIR"
+ fi
+
+ if [ -z "$(ls -A -- "tmp")" ]; then
+ rmdir "tmp"
+ fi
+
+ echo "$(tput setaf 2)Changes have been undone.$(tput sgr 0)"
+
+else
+ echo "$(tput setaf 1)Invalid command. Use 'add' to create a symlink or 'remove' to undo.$(tput sgr 0)"
+ exit 1
+fi