Move to Docusaurus

.github/workflows/build-documentation.yml

@@ -4,112 +4,111 @@ on:
   push:
     branches:
       - main
+  pull_request:
   workflow_dispatch:
 
+permissions:
+  contents: read
+  pull-requests: write   # to comment preview URL on PRs
+
 env:
-  INSTANCE: 'Writerside/strumenta'
-  DOCKER_VERSION: '243.21565'
+  NODE_OPTIONS: "--max_old_space_size=4096"
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs
     outputs:
-      algolia_artifact: ${{ steps.define-ids.outputs.algolia_artifact }}
-      artifact: ${{ steps.define-ids.outputs.artifact }}
+      preview_url: ${{ steps.netlify_preview.outputs.preview_url }}
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
         with:
-          fetch-depth: 0
-      - name: Define instance id and artifacts
-        id: define-ids
+          node-version: 18
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
         run: |
-            INSTANCE=${INSTANCE#*/}
-            INSTANCE_ID_UPPER=$(echo "$INSTANCE" | tr '[:lower:]' '[:upper:]')
-            ARTIFACT="webHelp${INSTANCE_ID_UPPER}2-all.zip"
-            ALGOLIA_ARTIFACT="algolia-indexes-${INSTANCE_ID_UPPER}.zip"
-
-            # Print the values
-            echo "INSTANCE_ID_UPPER: $INSTANCE_ID_UPPER"
-            echo "ARTIFACT: $ARTIFACT"
-            echo "ALGOLIA_ARTIFACT: $ALGOLIA_ARTIFACT"
-
-            # Set the environment variables and outputs
-            echo "INSTANCE_ID_UPPER=$INSTANCE_ID_UPPER" >> $GITHUB_ENV
-            echo "ARTIFACT=$ARTIFACT" >> $GITHUB_ENV
-            echo "ALGOLIA_ARTIFACT=$ALGOLIA_ARTIFACT" >> $GITHUB_ENV
-            echo "artifact=$ARTIFACT" >> $GITHUB_OUTPUT
-            echo "algolia_artifact=$ALGOLIA_ARTIFACT" >> $GITHUB_OUTPUT
-
-      - name: Build docs using Writerside Docker builder
-        uses: JetBrains/writerside-github-action@v4
-        with:
-          instance: ${{ env.INSTANCE }}
-          docker-version: ${{ env.DOCKER_VERSION }}
+          npm ci
+
+      - name: Type check
+        run: |
+          npx tsc -b
 
-      - name: Save artifact with build results
+      - name: Build Docusaurus
+        run: npx docusaurus build --no-minify
+
+      - name: Upload build artifact
         uses: actions/upload-artifact@v4
         with:
-          name: docs
-          path: |
-            artifacts/${{ steps.define-ids.outputs.artifact }}
-            artifacts/report.json
-            artifacts/${{ steps.define-ids.outputs.algolia_artifact }}
+          name: docusaurus-build
+          path: docs/build
           retention-days: 7
 
-#      - name: Upload build artifact
-#        uses: actions/upload-artifact@v4
-#        with:
-#          name: writerside-docs
-#          path: artifacts/
-#
-#      - name: Package Built Artifact
-#        run: |
-#          mkdir -p ./package
-#          cp artifacts/webHelpSTRUMENTA2-all.zip ./package/
-#          cd ./package
-#          echo '{ "name": "writerside-docs", "version": "1.0.0" }' > package.json
-
-      - name: Deploy to Netlify
+      # Preview deploy for PRs
+      - name: Netlify deploy preview
+        id: netlify_preview
+        if: ${{ github.event_name == 'pull_request' }}
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
         run: |
-          # Install Netlify CLI
-          npm install -g netlify-cli
-
-          # Unzip the generated artifact
-          mkdir -p extracted
-          unzip artifacts/${{ env.ARTIFACT }} -d extracted
-
-          # Deploy extracted content to Netlify
-          netlify deploy --prod --dir extracted
+          npm i -g netlify-cli
+          # Will return a draft URL. Capture it.
+          url=$(netlify deploy --dir build --json | jq -r '.deploy_url')
+          echo "preview_url=$url" >> $GITHUB_OUTPUT
 
-      - name: Create Release
-        id: create-release
-        uses: actions/create-release@v1
+      - name: Comment preview URL on PR
+        if: ${{ github.event_name == 'pull_request' && steps.netlify_preview.outputs.preview_url }}
+        uses: actions/github-script@v7
         with:
-          tag_name: v${{ github.run_number }}
-          release_name: Documentation Build - ${{ github.run_number }}
-          body: |
-            ## Documentation Build
-            This release contains the built documentation artifacts for version ${{ github.run_number }}.
-          draft: false
-          prerelease: false
+          script: |
+            const url = process.env.PREVIEW_URL;
+            const body = `✅ Netlify preview ready:\n\n${url}`;
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body
+            });
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PREVIEW_URL: ${{ steps.netlify_preview.outputs.preview_url }}
+
+  deploy:
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-      - name: Install GitHub CLI
-        run: sudo apt-get install -y gh
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docusaurus-build
+          path: build
 
-      - name: Upload Artifact to Release
-        run: |
-          gh release upload v${{ github.run_number }} artifacts/${{ env.ARTIFACT }} --clobber
+      - name: Deploy to Netlify (prod)
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Upload Algolia Artifact to Release
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
         run: |
-          gh release upload v${{ github.run_number }} artifacts/${{ env.ALGOLIA_ARTIFACT }} --clobber
+          npm i -g netlify-cli
+          netlify deploy --prod --dir build
+
+      # Create GitHub Release with a zipped build
+      - name: Zip build
+        run: (cd build && zip -r ../site.zip .)
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: site-${{ github.run_number }}
+          name: Docusaurus site ${{ github.run_number }}
+          files: site.zip
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,9 +1,69 @@
-# Starlasu
-This project contains the documentation on the Starlasu approach, which is 
-published [here](https://github.com/Strumenta/StarLasu/tree/main/documentation).
+# StarLasu
 
-## Publication
+The Starlasu approach provides a flexible, systematic, and extensible framework for creating tools like parsers, 
+transpilers, code analyzers, interpreters, code generators, and domain-specific languages (DSLs).
 
-We generate the documentation to be published using JetBrains's Writerside.
+## Documentation
 
-Updating the published version requires manually uploading the generated files to Netlify. At the moment Federico is the only one who has access.
+This project has been migrated from Writerside to **Docusaurus** for better maintainability and modern web standards.
+
+### Documentation Structure
+
+- **`docs/`** - Docusaurus-based documentation site
+- **`Writerside/`** - Original Writerside documentation (legacy)
+- **`webHelpSTRUMENTA2-all/`** - Generated web help files
+
+### Getting Started with Documentation
+
+1. **View Online**: The documentation is available at [https://starlasu.com](https://starlasu.com)
+
+2. **Local Development**:
+   ```bash
+   cd docs
+   npm install
+   npm start
+   ```
+
+3. **Build for Production**:
+   ```bash
+   cd docs
+   npm run build
+   ```
+
+## What is Starlasu?
+
+Starlasu consists of a mental framework and guidelines to build different components. For example, we have a detailed
+method to design and implement parsers (see [The Chisel Method](docs/docs/chisel-method)).
+
+Starlasu is supported by a family of libraries, each supporting the application of The Starlasu approach on 
+different platforms:
+
+- **Kolasu**: For the JVM (Java, Kotlin), expanding to Node.js and browser environments in version 1.6.
+- **Tylasu**: For Node.js and browser environments.
+- **Pylasu**: For Python.
+- **Sharplasu**: For .NET.
+
+These libraries share a common architecture and are interoperable. This enables cross-platform development and 
+consistent tooling.
+
+## Migration Notes
+
+The migration from Writerside to Docusaurus provides:
+
+- **Modern Web Standards**: Better performance and accessibility
+- **Improved Navigation**: Enhanced search and navigation capabilities
+- **Better Maintainability**: Easier to update and extend
+- **Responsive Design**: Works better on mobile and tablet devices
+- **Version Control**: Better integration with Git workflows
+
+## Contributing
+
+To contribute to the documentation:
+
+1. Make changes in the `docs/` directory
+2. Test locally with `npm start`
+3. Submit a pull request
+
+## License
+
+Copyright © Strumenta. Built with Docusaurus.