feat(site): add docs portal and adopt new PL/SQL branding icon

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install docs dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,9 @@
 *.vsix
 assets/
+!docs/assets/
+!docs/assets/icon.png
+!docs/assets/icon.svg
 node_modules/
+site/
+.venv-docs/
+.cache/

.vscodeignore

@@ -3,3 +3,9 @@ assets/**
 .gitignore
 *.vsix
 .github/**
+docs/**
+mkdocs.yml
+requirements-docs.txt
+scripts/**
+site/**
+.venv-docs/**

docs/changelog.md

@@ -0,0 +1,24 @@
+# Changelog
+
+A short release overview is maintained here for site visitors.
+
+## 1.2.0
+
+- added Marketplace-oriented metadata
+- introduced icon, banner settings, and release scripts
+- added changelog and CI workflow
+- improved README and repository presentation
+
+## 1.1.0
+
+- optimized grammar performance
+- standardized function scopes for better theme compatibility
+- prepared repository metadata for publishing
+
+## 1.0.0
+
+- first standalone release of the PL/SQL syntax extension
+- custom language id and grammar structure
+- MIT licensing and initial documentation
+
+For the full project history, see the repository changelog.

docs/coverage.md

@@ -0,0 +1,75 @@
+# Coverage
+
+## Supported syntax areas
+
+The current grammar covers the main structures expected in day-to-day PL/SQL work.
+
+### PL/SQL structures
+
+- anonymous blocks
+- procedures
+- functions
+- packages and package bodies
+- triggers
+- types and type bodies
+- records, collections, and `%TYPE` / `%ROWTYPE`
+- exception handling and control flow
+
+### SQL syntax
+
+- DML: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`
+- DDL: `CREATE`, `ALTER`, `DROP`, constraints, storage clauses
+- joins, ordering, grouping, predicates, and common modifiers
+
+### Literals and expressions
+
+- single-quoted strings
+- q-quote strings
+- national character strings
+- numeric literals
+- bind variables and substitution variables
+
+### Built-ins and runtime concepts
+
+- built-in functions grouped by category
+- predefined exceptions
+- SQL*Plus commands
+- common pseudocolumns and constants
+
+## Supported file extensions
+
+The extension currently registers these extensions with the `plsql` language id:
+
+```text
+.sql  .pls  .plsql  .pks  .pkb  .plb
+.fnc  .prc  .trg    .vw   .pkg  .pck
+.seq  .job  .src    .act  .bac  .bas
+.scr  .ut
+```
+
+## Validation assets
+
+The repository contains validation examples under `assets/examples` covering:
+
+- schema objects
+- packages and package bodies
+- standalone functions and procedures
+- triggers
+- views
+- anonymous blocks
+
+These files are used as manual test material while refining highlighting behavior.
+
+## Theme compatibility
+
+The grammar favors broad compatibility by using scope families that themes commonly style:
+
+- `comment.*`
+- `string.*`
+- `constant.*`
+- `storage.type.*`
+- `keyword.*`
+- `entity.name.function.*`
+- `variable.other.*`
+
+This improves the chance that tokens receive meaningful colors even in themes with limited custom scope rules.

docs/disclaimer.md

@@ -0,0 +1,17 @@
+# Disclaimer
+
+This project is an independent Visual Studio Code extension.
+
+It is not affiliated with, endorsed by, or related to Oracle Corporation.
+
+"Oracle", "PL/SQL", and "SQL*Plus" are trademarks or registered trademarks of Oracle Corporation. These names are used only to identify the language and tooling concepts supported by the extension.
+
+## License
+
+This project is released under the MIT License.
+
+## Repository scope
+
+The public repository contains the extension source, documentation, site configuration, and release-related files required to build and publish the project.
+
+Generated site output is intentionally excluded from version control.

docs/index.md

@@ -0,0 +1,66 @@
+# PL/SQL for VS Code
+
+<div class="hero">
+  <div>
+    <p class="eyebrow">Syntax highlighting extension</p>
+    <h1>Practical PL/SQL highlighting for real database code.</h1>
+    <p class="hero-copy">A focused Visual Studio Code extension for PL/SQL, SQL, packages, triggers, procedures, functions, and SQL*Plus scripts. Lightweight, theme-friendly, and built to stay easy to maintain.</p>
+    <div class="hero-actions">
+      <a class="md-button md-button--primary" href="installation/">Install manually</a>
+      <a class="md-button" href="coverage/">See coverage</a>
+    </div>
+    <p class="hero-note">Current status: production-ready for manual installation, with Marketplace publication planned next.</p>
+  </div>
+  <div class="hero-panel">
+
+```text
+Language ID: plsql
+Scope name : source.plsql
+Theme mode : light + dark
+Install     : VSIX (for now)
+Focus       : syntax quality and maintainability
+```
+
+  </div>
+</div>
+
+## Why this extension exists
+
+This project provides a dedicated PL/SQL highlighting experience for VS Code without bundling unnecessary extension features. It is designed for people who work with database code daily and want a grammar that stays organized, fast, and predictable.
+
+<div class="card-grid" markdown>
+
+-   ### Lightweight by design
+
+    The extension focuses on syntax highlighting and language registration only. No extra runtime features, no unnecessary payload.
+
+-   ### Theme-compatible scopes
+
+    The grammar uses broadly supported scope families such as `entity.name.function.*`, `keyword.*`, and `storage.type.*` for better compatibility across popular themes.
+
+-   ### Ready for real PL/SQL files
+
+    Common file types like `.sql`, `.pls`, `.pks`, `.pkb`, `.fnc`, `.prc`, `.trg`, and SQL*Plus-style scripts are already mapped.
+
+-   ### Easy to maintain
+
+    The grammar, docs, validation scripts, and release workflow are organized to keep future changes simple.
+
+</div>
+
+## Current release snapshot
+
+| Item | Value |
+| --- | --- |
+| Extension name | PL/SQL |
+| Current site branch | `site` |
+| Current extension version | `1.2.0` |
+| Install method | Manual VSIX installation |
+| Next milestone | Marketplace publication |
+
+## What you can do next
+
+1. Read the [overview](overview.md) to understand the project status and goals.
+2. Follow the [installation guide](installation.md) to build and install locally.
+3. Review [coverage](coverage.md) for supported syntax areas and file extensions.
+4. Use the [roadmap](roadmap.md) page to keep upcoming work visible.

docs/installation.md

@@ -0,0 +1,74 @@
+# Installation
+
+## Current installation method
+
+The extension is not published to the Marketplace yet, so installation is currently manual via VSIX.
+
+## Build locally
+
+From the repository root:
+
+```bash
+npm run validate:grammar
+npm run package
+```
+
+This generates a file like:
+
+```text
+vscode-plsql-syntax-1.2.0.vsix
+```
+
+## Install in VS Code
+
+```bash
+code --install-extension vscode-plsql-syntax-1.2.0.vsix --force
+```
+
+Then reload the window:
+
+```text
+Developer: Reload Window
+```
+
+## Validate highlighting
+
+Open one or more example files from `assets/examples` and inspect tokens if needed with:
+
+```text
+Developer: Inspect Editor Tokens and Scopes
+```
+
+## Local site preview
+
+The documentation site can also be tested locally before publishing.
+
+### Start preview server
+
+```bash
+./scripts/serve-docs.sh
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8000
+```
+
+### Build static site
+
+```bash
+./scripts/build-docs.sh
+```
+
+### Run a simple offline validation
+
+```bash
+./scripts/test-docs.sh
+```
+
+## Notes
+
+- Generated site files go to `site/` and are ignored by Git.
+- The local Python environment is stored in `.venv-docs/` and is also ignored.
+- Marketplace publication can be added later without changing the documentation structure.