chore(website): add VitePress documentation site ported from the wiki

.github/dependabot.yml

@@ -35,3 +35,17 @@ updates:
       - dependency-name: "@types/node"
         update-types:
           - version-update:semver-major
+
+  # The documentation site is a standalone pnpm project.
+  - package-ecosystem: npm
+    directory: /website
+    commit-message:
+      prefix: "chore(website): "
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      website:
+        patterns:
+          - "*"

.github/workflows/pages.yml

@@ -0,0 +1,70 @@
+name: pages
+
+# Builds the documentation site in `website/`. This workflow is independent
+# from the extension build and test workflows.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'website/**'
+      - '.github/workflows/pages.yml'
+  pull_request:
+    paths:
+      - 'website/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # VitePress reads git history for the "last updated" timestamps.
+          fetch-depth: 0
+      - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
+        with:
+          package_json_file: website/package.json
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+          cache: 'pnpm'
+          cache-dependency-path: website/pnpm-lock.yaml
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      # The build fails on dead internal links.
+      - name: Build site
+        run: pnpm run docs:build
+      - name: Upload site
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: website/docs/.vitepress/dist
+
+  # Requires "Settings > Pages > Build and deployment > Source" to be set to
+  # "GitHub Actions". After enabling it, run this workflow manually to publish
+  # the site without waiting for a change under `website/`.
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

ThirdPartyNotices.txt

@@ -23,8 +23,9 @@ R logo
 Copyright (c) 2016 The R Foundation.
 Source: https://www.r-project.org/logo/
 
-Files: images/Rlogo.svg and images/Rlogo.png.
-The SVG reproduces the official artwork unchanged. The PNG is an 800 x 700
+Files: images/Rlogo.svg, images/Rlogo.png, and website/docs/public/logo.svg.
+The SVGs reproduce the official artwork unchanged; the copy under website is
+used by the documentation site and is not part of the extension package. The PNG is an 800 x 700
 raster variant used as the extension icon.
 
 The logo is distributed under Creative Commons Attribution-ShareAlike 4.0

website/.gitignore

@@ -0,0 +1,3 @@
+docs/.vitepress/cache
+docs/.vitepress/dist
+node_modules

website/README.md

@@ -0,0 +1,21 @@
+# vscode-R documentation site
+
+Source of the vscode-R documentation site, built with
+[VitePress](https://vitepress.dev/). Pages live in [`docs`](docs), and the
+navigation is defined in [`docs/.vitepress/config.mjs`](docs/.vitepress/config.mjs).
+
+This directory is a standalone pnpm project: it has its own `package.json`,
+`pnpm-lock.yaml`, and `pnpm-workspace.yaml`, and is not part of the extension
+package at the repository root.
+
+[`docs/public/logo.svg`](docs/public/logo.svg) is an unchanged copy of the
+[R logo](https://www.r-project.org/logo/), © 2016 The R Foundation, licensed
+under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). See
+[`ThirdPartyNotices.txt`](../ThirdPartyNotices.txt).
+
+```sh
+cd website
+pnpm install --frozen-lockfile
+pnpm run docs:dev     # local preview with hot reload
+pnpm run docs:build   # production build; fails on dead internal links
+```

website/docs/.vitepress/config.mjs

@@ -0,0 +1,121 @@
+import { defineConfig } from 'vitepress';
+
+const repo = 'https://github.com/REditorSupport/vscode-R';
+
+export default defineConfig({
+    lang: 'en-US',
+    title: 'vscode-R',
+    titleTemplate: ':title | R Extension for Visual Studio Code',
+    description:
+        'Documentation for vscode-R, the R Extension for Visual Studio Code: installation, configuration, and features.',
+    // Served from https://reditorsupport.github.io/vscode-R/
+    base: '/vscode-R/',
+    cleanUrls: true,
+    // Requires full git history at build time (`fetch-depth: 0` in CI).
+    lastUpdated: true,
+    markdown: {
+        // Shiki has no DCF grammar; DESCRIPTION-style `Key: value` reads fine as YAML.
+        languageAlias: { dcf: 'yaml' },
+    },
+    head: [['link', { rel: 'icon', type: 'image/svg+xml', href: '/vscode-R/logo.svg' }]],
+    themeConfig: {
+        logo: '/logo.svg',
+        nav: [
+            { text: 'Getting Started', link: '/getting-started' },
+            {
+                text: 'Installation',
+                items: [
+                    { text: 'Windows', link: '/installation/windows' },
+                    { text: 'macOS', link: '/installation/macos' },
+                    { text: 'Linux', link: '/installation/linux' },
+                ],
+            },
+            {
+                text: 'Links',
+                items: [
+                    {
+                        text: 'VS Code Marketplace',
+                        link: 'https://marketplace.visualstudio.com/items?itemName=REditorSupport.r',
+                    },
+                    { text: 'Open VSX', link: 'https://open-vsx.org/extension/REditorSupport/r' },
+                    { text: 'Changelog', link: `${repo}/blob/main/CHANGELOG.md` },
+                ],
+            },
+        ],
+        sidebar: [
+            {
+                text: 'Introduction',
+                items: [{ text: 'Getting Started', link: '/getting-started' }],
+            },
+            {
+                text: 'Installation',
+                items: [
+                    { text: 'Windows', link: '/installation/windows' },
+                    { text: 'macOS', link: '/installation/macos' },
+                    { text: 'Linux', link: '/installation/linux' },
+                ],
+            },
+            {
+                text: 'Configuration',
+                items: [
+                    { text: 'Extension settings', link: '/configuration/extension-settings' },
+                    { text: 'Keyboard shortcuts', link: '/configuration/keyboard-shortcuts' },
+                    { text: 'Code linting', link: '/configuration/code-linting' },
+                    {
+                        text: 'Recommended extensions and configuration',
+                        link: '/configuration/recommended-extensions',
+                    },
+                    { text: 'Working with renv-enabled projects', link: '/configuration/renv' },
+                ],
+            },
+            {
+                text: 'Features',
+                items: [
+                    { text: 'R Language Service', link: '/features/language-service' },
+                    { text: 'Interacting with R terminals', link: '/features/r-terminals' },
+                    { text: 'R Interactive (experimental)', link: '/features/r-interactive' },
+                    { text: 'Interactive viewers', link: '/features/interactive-viewers' },
+                    { text: 'Sidebar user interface', link: '/features/sidebar' },
+                    { text: 'Plot viewer', link: '/features/plot-viewer' },
+                    { text: 'R Session watcher', link: '/features/session-watcher' },
+                    { text: 'RStudio addin support', link: '/features/rstudio-addins' },
+                ],
+            },
+            {
+                text: 'Guides',
+                items: [
+                    { text: 'Package development', link: '/guide/package-development' },
+                    { text: 'R Markdown', link: '/guide/r-markdown' },
+                ],
+            },
+            {
+                text: 'Project',
+                items: [
+                    { text: 'Contributing', link: '/contributing' },
+                    { text: 'FAQ', link: '/faq' },
+                ],
+            },
+            {
+                text: 'Removed in 3.0.0',
+                collapsed: true,
+                items: [
+                    { text: 'R options', link: '/configuration/r-options' },
+                    { text: 'Live Share collaboration', link: '/features/live-share' },
+                ],
+            },
+        ],
+        socialLinks: [{ icon: 'github', link: repo }],
+        search: { provider: 'local' },
+        editLink: {
+            pattern: `${repo}/edit/main/website/docs/:path`,
+            text: 'Edit this page on GitHub',
+        },
+        outline: { level: [2, 3] },
+        footer: {
+            message: 'Released under the MIT License.',
+            // Attribution required by the logo's CC BY-SA 4.0 license.
+            copyright:
+                'The <a href="https://www.r-project.org/logo/">R logo</a> is © 2016 The R Foundation, used under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>.',
+        },
+    },
+});

website/docs/configuration/code-linting.md

@@ -0,0 +1,67 @@
+# Code linting
+
+R code linting (diagnostics) is provided by [lintr](https://github.com/r-lib/lintr) via language server and is enabled by default. It provides syntax error warnings as well as style guidelines.
+
+To disable diagnostics, you might add the following to the VS Code settings:
+
+```json
+{
+  "r.lsp.diagnostics": false
+}
+```
+
+However, you will not be notified if syntax errors in the code are detected.
+
+## Customize
+
+The [default](https://lintr.r-lib.org/articles/lintr.html#defaults) linting behaviour is based on the `tidyverse` style guide, which you may not find to your liking. To customize, you should create/edit the global lintr config file at `~/.lintr`. Alternatively, you can also create/edit a project-specific lintr config file at `${workspaceFolder}/.lintr`. Some example of customized lintr files are provided below.
+
+- Visit [Individual linters](https://lintr.r-lib.org/reference/index.html#individual-linters) for a complete list of supported linters.
+- Visit the [Configuring linters](https://lintr.r-lib.org/articles/lintr.html#configuring-linters) for a complete guide to customizing lintr config regarding the list of linters and file or line exclusions.
+
+### Examples
+
+#### Only detect syntax errors:
+
+```
+linters: list()
+```
+
+#### Deviate from [default linters](https://lintr.r-lib.org/reference/default_linters.html):
+
+Here's an example of a simple `~/.lintr` override, where we turn off the `<-` assignment linter (i.e., `=` is fine) and adjust the number of characters in each line.
+
+```
+linters: linters_with_defaults(
+   assignment_linter = NULL,
+   line_length_linter(120)
+  )
+```
+
+(Note: the leading space in front of the final parenthesis is deliberate, since it is required for the DCF format.)
+
+Here's a more aggressive example, where we override multiple defaults. Background [here](https://github.com/REditorSupport/vscode-R/issues/1400).
+
+```
+linters: linters_with_defaults(
+   assignment_linter     = NULL, # allow `=` for assignment
+   commented_code_linter = NULL, # allow commented-out code
+   line_length_linter    = NULL, # lintr default is 80 chars
+   object_name_linter    = NULL, # allow any naming style (e.g., camelCase)
+   object_usage_linter   = NULL, # skip checks for undefined/unused variables
+   quotes_linter         = NULL, # allow single quotes
+   semicolon_linter      = NULL, # allow semicolons
+   whitespace_linter     = NULL  # allow tabs for indentation
+  )
+```
+
+#### Only use specified linters:
+
+```
+linters: list(
+  commas_linter(),
+  duplicate_argument_linter(),
+  missing_argument_linter(),
+  missing_package_linter(),
+  namespace_linter())
+```