Writerside (#503)

* migrating documentation to Writerside

* migrating documentation to Writerside

.github/workflows/mkdocs.yml

@@ -1,21 +1,74 @@
 name: Build & Deploy Docs
 on:
   push:
-    branches:
-      - master
-    paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
+    # To trigger the workflow once you push to the `main` branch
+    # Replace `main` with your branch’s name
+    branches: ["main"]
+  # Specify to run a workflow manually from the Actions tab on GitHub
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  pages: write
+
+env:
+  # Name of module and id separated by a slash
+  INSTANCE: Writerside/fd
+  # Replace XX with the ID of the instance in capital letters
+  ARTIFACT: webHelpFD2-all.zip
+  # Docker image version
+  DOCKER_VERSION: 241.15989
 
 jobs:
   build:
-    name: Deploy docs
     runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build Writerside docs using Docker
+        uses: JetBrains/writerside-github-action@v4
+        with:
+          instance: ${{ env.INSTANCE }}
+          artifact: ${{ env.ARTIFACT }}
+          docker-version: ${{ env.DOCKER_VERSION }}
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: |
+            artifacts/${{ env.ARTIFACT }}
+          retention-days: 7
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # Requires build job results
+    needs: build
+    runs-on: ubuntu-latest
+
     steps:
-      - name: Checkout master
-        uses: actions/checkout@v1
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+
+      - name: Unzip artifact
+        run: unzip -O UTF-8 -qq ${{ env.ARTIFACT }} -d dir
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4.0.0
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3.0.1
+        with:
+          path: dir
 
-      - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4.0.4

Writerside/c.list

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>

Writerside/cfg/buildprofiles.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+    <variables></variables>
+    <build-profile instance="fd">
+        <variables>
+            <noindex-content>true</noindex-content>
+        </variables>
+    </build-profile>
+
+</buildprofiles>

Writerside/fd.tree

@@ -0,0 +1,71 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="fd"
+                  name="Fred Docs" start-page="index.md">
+    <toc-element topic="index.md"/>
+    <toc-element topic="fred_for_existing_modxers.md"/>
+    <toc-element topic="getting_started.md"/>
+    <toc-element topic="templates.md"/>
+    <toc-element topic="elements.md"/>
+    <toc-element topic="blueprints.md"/>
+    <toc-element toc-title="Creating a Theme">
+        <toc-element topic="themer_index.md"/>
+        <toc-element topic="themes.md"/>
+        <toc-element topic="convert-to-fred.md"/>
+        <toc-element toc-title="Fred Templates">
+            <toc-element topic="templates_index.md"/>
+        </toc-element>
+        <toc-element toc-title="Fred Elements">
+            <toc-element topic="elements_index.md"/>
+            <toc-element topic="markup.md"/>
+            <toc-element topic="attributes.md"/>
+            <toc-element topic="js_events.md"/>
+        </toc-element>
+        <toc-element toc-title="Fred Options">
+            <toc-element topic="options_index.md"/>
+            <toc-element topic="settings.md"/>
+            <toc-element topic="import.md"/>
+            <toc-element topic="override.md"/>
+        </toc-element>
+        <toc-element toc-title="Fred CMP">
+            <toc-element topic="cmp_elements.md"/>
+            <toc-element topic="element_categories.md"/>
+            <toc-element topic="option_sets.md"/>
+            <toc-element topic="rte_configs.md"/>
+            <toc-element topic="rebuild.md"/>
+            <toc-element topic="cmp_blueprints.md"/>
+            <toc-element topic="blueprint_categories.md"/>
+            <toc-element topic="cmp_themes.md"/>
+            <toc-element topic="themed_templates.md"/>
+            <toc-element topic="media_sources.md"/>
+            <toc-element topic="theme_settings_and_resolvers.md"/>
+        </toc-element>
+        <toc-element topic="rte_configs_index.md"/>
+        <toc-element topic="system_settings_index.md"/>
+        <toc-element topic="media_sources_index.md"/>
+    </toc-element>
+    <toc-element toc-title="Site Administration">
+        <toc-element toc-title="ACLs">
+            <toc-element topic="howto.md"/>
+            <toc-element topic="permissions.md"/>
+            <toc-element topic="policies.md"/>
+        </toc-element>
+    </toc-element>
+    <toc-element toc-title="Using with Gitify">
+        <toc-element topic="collab_index.md"/>
+        <toc-element topic="gitify.md"/>
+        <toc-element topic="initial_extract.md"/>
+        <toc-element topic="gitify_in_action.md"/>
+        <toc-element topic="pr_workflow.md"/>
+    </toc-element>
+    <toc-element toc-title="Plugin Development">
+        <toc-element topic="developer_index.md"/>
+        <toc-element topic="sidebar_plugins.md"/>
+        <toc-element topic="toolbar_plugins.md"/>
+        <toc-element topic="modx_events.md"/>
+    </toc-element>
+
+    <toc-element topic="credits.md"/>
+</instance-profile>

docs/collab/index.md → Writerside/topics/collab/collab_index.md

@@ -9,7 +9,7 @@ Collaborating on Themes can be a great way to build a robust solution you can sh
 
 ## The Simple Way
 
-The easiest way to collaborate on a Theme is to simply invite a group of people to a site and to have them work away. [Export your Theme](../themer/cmp/themes) when your happy with the results, and you’re done!
+The easiest way to collaborate on a Theme is to simply invite a group of people to a site and to have them work away. [Export your Theme](themes.md) when your happy with the results, and you’re done!
 
 ## The “Right” Way
 

docs/collab/gitify.md → Writerside/topics/collab/gitify.md

@@ -18,7 +18,7 @@ Start by creating a blank MODX instance using the latest version. You’ll also
 
 Once the instance is created, `ssh` into it and execute the following commands starting in the home directory. This will install Composer and copy Gitify to your site.
 
-```plain
+```bash
 cd www; curl http://modx.co/scripts/install.sh | sh
 mkdir ../gitify; cd ../gitify
 git clone https://github.com/modmore/Gitify.git ./
@@ -30,7 +30,7 @@ Now exit the SSH session, and log back in so you can use Composer. Alternately,
 
 From an SSH connection in the Cloud home directory:
 
-```plain
+```bash
 cd ~/gitify
 composer install
 chmod +x Gitify; cd ~/.bin; ln -s ../gitify/Gitify gitify
@@ -48,34 +48,34 @@ To start a new Theme project, see the [Setting up a Theme to work with Gitify](i
 
 Because you cannot `git clone` into a directory with anything in it, we’ll use a temporary location and move the files to the web root. To get the URL to clone, click the down-arrow on the green `Clone or download` button on a Theme Github project and copy the SSH URL which looks like `git@github.com:modxcms/fred-theme-starter.git`
 
-```plain
+```bash
 cd ~/www
 git clone git@github.com:modxcms/fred-theme-starter.git tmp
 ```
 
 This will download the theme repository into a `~/www/tmp/` directory in the Cloud. Next, move the contents of `tmp/` to the correct location under `www/`:
 
-```plain
+```bash
 rsync -av ./tmp ./
 ```
 
 Make sure the `.git/` directory and files are move under `www/`. Once you confirm things are in the right place, go ahead and remove `tmp/`:
 
-```plain
+```bash
 rm -rf ./tmp
 ```
 
 ### Step 5: Load the Theme using Gitify
 
 Now it’s time to load the Theme into your MODX instance. This will most likely include several Extras and take a a minute or longer depending on the speed of your connection. You’ll see messages about downloading and installing Extras during this process:
 
-```plain
+```bash
 cd ~/www
 gitify package:install --all
 gitify build
 ```
 
-You should see a green one-word message `Done!` if the install is successful, and the same but with memory and timing stats if the build is successful.
+You should see a green one-word message `Done!` if the installation is successful, and the same but with memory and timing stats if the build is successful.
 
 ### Step 6: Login to the Manager to view your Theme
 

docs/collab/gitify_in_action.md → Writerside/topics/collab/gitify_in_action.md

@@ -12,7 +12,7 @@ For the purpose of this tutorial, we’ll assume all users can commit directly t
 
 It’s critical to make sure that you don’t lose work when collaborating with a team. To prevent accidental overwrites, always perform the following before pulling from or pushing to the orign repository.
 
-```plain
+```bash
 cd ~/www
 gitify extract
 git status
@@ -26,7 +26,7 @@ This step and step 4 below can be skipped if ther are no changes to commit.
 
 If you do have changes, first commit them to your local repository before continuing:
 
-```plain
+```bash
 git add --all  # or git add on files you want to commit
 git commit -m "Your commit message here"  # please write your own message
 ```
@@ -35,15 +35,15 @@ git commit -m "Your commit message here"  # please write your own message
 
 Now it is time to sync all the latest updates from the upstream origin repository. From webroot, enter the following command:
 
-```plain
+```bash
 git pull origin master
 ```
 
 This may result in conflicts that will be noted. If there are conflicts, they must be resolved before you can continue. A conflict happens when two people change the same line of code. For information on resolving conflicts, please see [Github’s guide to resolving conflicts](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/).
 
 Once you resolve conflicts, or after you have pulled from the origin, build the changes and make sure everything is functioning as expected in MODX:
 
-```plain
+```bash
 gitify package:install --all
 gitify build
 ```
@@ -54,7 +54,7 @@ If you are only pulling remote changes, skip this step as in step 2 above.
 
 Now you can safely push your changes. You’ll see messages about Extracting various Fred-related things. If you delay pushing your changes, you may see an error message about (new) conflicts due to other collaborators pushing changes before you:
 
-```plain
+```bash
 git push origin master
 ```
 

docs/collab/initial_extract.md → Writerside/topics/collab/initial_extract.md

@@ -8,7 +8,7 @@ Note the URL for this project, by clicking the down-arrow on the green `Clone or
 
 SSH into your Cloud, and switch to the `www/` webroot directory. Then initialize git with the following command, using the SSH URL from above:
 
-```plain
+```bash
 git init
 git remote add origin git@github.com:your_name/example_theme.git
 ```
@@ -17,7 +17,7 @@ git remote add origin git@github.com:your_name/example_theme.git
 
 Create a `.gitingnore` file to exclude MODX and other files that are not needed with the following content. Make sure to change `!/assets/themes/{{your-theme-name}}` to its actual name like `!/assets/themes/lightcoral`:
 
-```plain
+```text
 # MODX & Gitify #
 #################
 /_backup
@@ -95,7 +95,7 @@ This will instruct Gitify to include all Elements and categories, their Option S
 
 Now it’s time to push the code to the source repo. Once you’ve reached a point where you are ready to share and collaborate on a theme, execute the following:
 
-```plain
+```bash
 cd ~/www
 gitify extract
 git add --all  # or git add on files you want to commit

docs/collab/pr_workflow.md → Writerside/topics/collab/pr_workflow.md

@@ -18,14 +18,14 @@ Click the down-arrow on the green `Clone or download` button on a source Github
 
 Because `git clone` only works in empty directories, we’ll use a temporary `tmp/` directory and move the files to the web root when done. Open an SSH connection to your working Cloud instance and execute:
 
-```plain
+```bash
 cd ~/www
 git clone git@github.com:your_username/your-fork-name.git tmp
 ```
 
 This will download the theme repository into a `~/www/tmp/` directory in the Cloud. Next, move the contents of `tmp/` to the correct location under `www/`:
 
-```plain
+```bash
 rsync -av ./tmp ./
 ```
 
@@ -35,7 +35,7 @@ Make sure the `.git/` directory and files are moved under webroot `www/` directo
 
 This is the original project. Use its HTTPS clone URL from step 1 of this tutorial to set the remote upstream:
 
-```plain
+```bash
 git remote add upstream https://github.com/modxcms/fred-theme-starter.git
 ```
 
@@ -49,7 +49,7 @@ For the purposes of working with PRs, you should _never_ commit directly to your
 
 Before pushing any work to a feature branch, you should sync your local repository with the upstream. For more information on syncing forks see the [Syncing a fork](https://help.github.com/articles/syncing-a-fork/) guide:
 
-```plain
+```bash
 git checkout master
 git fetch upstream
 git merge --ff-only upstream/master  # only merges if local is clean
@@ -64,7 +64,7 @@ These commands are only needed when there is a differnce between the commit vers
 
 The following commands create your local feature branch, and commits them to the local git repo.
 
-```plain
+```bash
 cd ~/www
 git checkout -b my-feature   # checkout to a new branch named `my-feature`,
                              # or any other name you decide for your work
@@ -75,7 +75,7 @@ git commit -m "My Changes"   # Use a more reasonable commit message
 
 Next, we sync upstream master branch with your fork.
 
-```plain
+```bash
 git checkout master
 git fetch upstream
 git merge --ff-only upstream/master
@@ -84,7 +84,7 @@ git push origin master
 
 Now, we sync the feature branch with any changes from the master branch of the fork from the previous merge step.
 
-```plain
+```bash
 git checkout my-feature      # checkout your `my-feature` branch again
 git rebase master            # this pulls from your forked master```
 ```
@@ -93,14 +93,14 @@ This may result in conflicts that will be noted. If there are conflicts, they mu
 
 Finally, we build all the changes into your working MODX instance with Gitify.
 
-```plain
+```bash
 gitify package:install --all
 gitify build
 ```
 
 Double check to make sure the Theme and the changes still work as expected. Then commit them to your Github fork, where it can then be submitted as a PR to the original upstream project:
 
-```plain
+```bash
 git push origin my-feature   # push to your `my-feature` branch on Github to
                              # submit as a PR, per the next section below
 git checkout master          # return to the master branch to start your next