docs: write a usage and contribution guide

A goal is to make it easier for new contributors to get started.

.eslintignore

@@ -0,0 +1,2 @@
+vscode-extension/test/e2e/
+vscode-extension/test/web/

.eslintrc.json

@@ -14,6 +14,7 @@
 	],
 	"plugins": ["@typescript-eslint", "prettier", "import"],
 	"rules": {
+		"@typescript-eslint/ban-types": "off",
 		"@typescript-eslint/no-namespace": "off",
 		"@typescript-eslint/no-explicit-any": "off",
 		"import/no-unresolved": "off",

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [wkillerud]
+ko_fi: williamkillerud

.gitignore

@@ -4,6 +4,8 @@
 logs/
 *.log
 npm-debug.log*
+.cpuprofile
+.heapprofile
 
 # Dependency directory
 node_modules/

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-	"recommendations": ["amodio.tsl-problem-matcher"]
+	"recommendations": ["vitest.explorer"]
 }

.vscode/launch.json

@@ -12,7 +12,7 @@
 			"autoAttachChildProcesses": true
 		},
 		{
-			"name": "Launch Web Extension in VS Code",
+			"name": "Launch web extension",
 			"type": "extensionHost",
 			"debugWebWorkerHost": true,
 			"request": "launch",
@@ -24,51 +24,14 @@
 			"autoAttachChildProcesses": true
 		},
 		{
-			"name": "Integration Tests",
+			"name": "Launch end-to-end tests",
 			"type": "extensionHost",
 			"request": "launch",
 			"runtimeExecutable": "${execPath}",
 			"args": [
 				"--extensionDevelopmentPath=${workspaceFolder}/vscode-extension",
-				"--extensionTestsPath=${workspaceFolder}/vscode-extension/out/test/e2e/suite",
-				"${workspaceFolder}/vscode-extension/out/test/fixtures/"
-			],
-			"outFiles": ["${workspaceFolder}/vscode-extension/out/test/e2e/**/*.js"]
-		},
-		{
-			"type": "chrome",
-			"request": "attach",
-			"name": "Attach to web integration test",
-			"skipFiles": ["<node_internals>/**"],
-			"port": 9229,
-			"timeout": 30000, // give it time to download vscode if needed
-			"resolveSourceMapLocations": [
-				"!**/vs/**", // exclude core vscode sources
-				"!**/static/build/extensions/**" // exclude built-in extensions
-			],
-			"presentation": {
-				"hidden": true
-			}
-		},
-		{
-			"type": "node",
-			"request": "launch",
-			"name": "Launch web integration test",
-			"outputCapture": "std",
-			"program": "${workspaceFolder}/vscode-extension/out/test/web/runTest.js",
-			"args": ["--waitForDebugger=9229"],
-			"cascadeTerminateToConfigurations": ["Launch web integration test"],
-			"presentation": {
-				"hidden": true
-			}
-		}
-	],
-	"compounds": [
-		{
-			"name": "Web Integration Tests",
-			"configurations": [
-				"Launch web integration test",
-				"Attach to web integration test"
+				"--extensionTestsPath=${workspaceFolder}/vscode-extension/test/e2e/suite",
+				"${workspaceFolder}/vscode-extension/test/fixtures/"
 			]
 		}
 	]

.vscode/settings.json

@@ -1,5 +1,4 @@
 {
-	"mochaExplorer.cwd": "server",
 	"somesass.scannerDepth": 30,
 	"somesass.scannerExclude": [
 		"**/.git/**",

CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+While not an official Sass project, we strive to follow the [Sass Community Guidelines](https://sass-lang.com/community-guidelines/).
+
+- Be considerate
+- Be open and inviting
+- Be respectful
+- Take responsibility for our words and actions
+- Be collaborative
+- Value decisiveness, clarity and open communication
+- Be responsive and helpful
+- Step down considerately

CONTRIBUTING.md

@@ -1,152 +1,8 @@
 # Contributing
 
-Thank you for showing an interest in contributing, be it to the language server or to the VS Code extension 🌟
+Thank you for showing an interest in contributing, be it to the language server, to the VS Code extension, the documentation, or in some other way 🌟
 
-Before you start, please make a [new Issue](https://github.com/wkillerud/some-sass/issues/new/choose). I don't always make new issues for all the things I work on. By making a new Issue we can avoid duplicating our efforts.
-
-## Development environment
-
-You need these things installed:
-
-- Node.js LTS
-- For the VS Code extension, but recommended either way:
-  - Visual Studio Code stable
-  - The extension _TypeScript + Webpack Problem Matchers_ (`amodio.tsl-problem-matcher`)
-
-```
-# install dependencies
-npm install
-# confirm existing tests are running
-npm test
-```
-
-### If using VS Code
-
-Go to the _Run and Debug_ pane in VS Code and run _Launch extension_. Rebuild the project and restart the debugging session to see changes take effect.
-
-If you get a warning, ensure you have the _TypeScript + Webpack Problem Matchers_ (`amodio.tsl-problem-matcher`) extension installed and active.
-
-## Architecture
-
-This extension consists of a [client for VS Code](https://github.com/wkillerud/some-sass/blob/main/vscode-extension) and a [language server](https://github.com/wkillerud/some-sass/blob/main/packages/language-server). The client starts the server on activation.
-
-The server then:
-
-1. [scans the workspace](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/scanner.ts)
-2. [parses](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/parser/parser.ts) SCSS code
-3. puts the parsed documents in a [in-memory context](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/context-provider.ts)
-
-The client requests information from the server when needed, and notifies the server when a file changes.
-
-See [packages/langauge-server/src/server.ts](https://github.com/wkillerud/some-sass/blob/main/packages/langauge-server/src/server.ts) for the event listeners on the server side, and the [features folder in the server](https://github.com/wkillerud/some-sass/tree/main/packages/language-server/src/features) for code supporting the different features.
-
-```mermaid
-sequenceDiagram
-    Client->>+Server: Extension activated
-    Server->Server: Scans for SCSS
-    Server->-Server: Parses SCSS
-    Client->>Server: Hover
-    Server-->>Client: Provide hover info
-    Client->>+Server: Changing file
-    Server->Server: Re-parse changed file
-    Server-->>-Client: Provide code suggestions
-```
-
-### Browser version
-
-This extension also works with VS Code in the browser. It works more or less the same as the regular Node version, except it doesn't have direct access to the file system.
-
-To work around this, [the server](https://github.com/wkillerud/some-sass/blob/main/packages/language-server/src/file-system-provider.ts) makes requests to [the client](https://github.com/wkillerud/some-sass/blob/main/vscode-extension/src/client.ts), which then uses the [FileSystem API](https://code.visualstudio.com/api/references/vscode-api#FileSystem) to work with files and directories, before sending the result back to the server.
-
-```mermaid
-sequenceDiagram
-    Client->>Server: Extension activated
-    Server->>Client: Get list of files in the workspace
-    Client-->>Server: List of files
-    Server->>Client: Get contents of file
-    Client-->>+Server: Contents of file
-    Server->-Server: Parse SCSS
-    Client->>Server: Hover
-    Server-->>Client: Provide hover info
-```
-
-## Manual testing
-
-To test your changes in VS Code:
-
-- Go to the Run and Debug section
-- Run the `Launch extension` configuration
-
-A new window should open with the title `[Extension Development Host]`. In this window you can open whatever project you want to use for testing. If you don't have one you can open the folder `vscode-extension/test/fixtures/` in this repository.
-
-Every time you make a change you need to restart `Launch extension`.
-
-Test your changes and see if they work.
-
-### Test the browser version
-
-This extension also works in the browser. Run `npm run start:web` to open VS Code in a browser and test your changes.
-
-Docs: [Test your web extension](https://code.visualstudio.com/api/extension-guides/web-extensions#test-your-web-extension)
-
-## Debugging
-
-### Debugging the Node (or regular) version
-
-You can set breakpoints to inspect what happens in your code. At time of writing you must set these breakpoints in the _compiled output_ in `vscode-extension/dist/node-server.js`.
-
-Open `vscode-extension/dist/node-server.js`, search for a function name close to where you want to debug, and place breakpoints where you would like. Then:
-
-- Go to the Run and Debug pane in VS Code.
-- Select `Launch extension` and start debugging.
-
-You should see the code pause on your breakpoint. If not, try to place breakpoints elsewhere. Something unexpected may stop you from reaching your code.
-
-### Debugging the browser version
-
-You have two options when to debug the browser version:
-
-1. Run in VS Code:
-
-   - Go to the Run and Debug section
-   - Run the _Launch Web Extension in VS Code_ configuration
-   - Open `vscode-extension/dist/browser-server.js`, search for a function name close to where you want to debug, and place breakpoints where you would like.
-
-2. Run in Chromium:
-   - In a terminal, run `npm run start:web`
-   - Open the Chromium developer tools and set breakpoints in the Sources pane.
-
-### Debugging unit tests
-
-Tests compile to `packages/language-server/out/test/`. If you want to debug using a unit test, you have to set breakpoints on the compiled output.
-
-Find your test, or the code you want to debug in the `packages/language-server/out/` folder, and set breakpoints.
-
-The extension Mocha Test Explorer (`hbenl.vscode-mocha-test-adapter`) is useful to launch individual tests in debug mode. Install the extension, open your unit test, and press the Debug button that should appear over your test.
-
-### Debugging integration tests
-
-Integration tests run in the Extension Development Host, and are more realistic than unit tests. However, sometimes they can be tricky to write. You can debug the tests themselves.
-
-This method of debugging is **not recommended** if you want to debug the functionality itself. Instead, debug using the Client + Server configuration explained above, and perform the test manually.
-
-If you want to debug the integration tests there are a few things to keep in mind, since tests run in this way use your main stable install of VS Code (not Insiders, like from the terminal):
-
-- You will need to install Vetur (`octref.vetur`), Astro (`astro-build.astro-vscode`) and Svelte for VS Code (`svelte.svelte-vscode`).
-- You **must** use default settings for Some Sass. Tip: use the included Workspace Settings.
-- To compile changes in test code, run `npm run compile` in the `e2e` directory.
-
-You set breakpoints in the compiled output. Integration tests compile to `vscode-extension/out/suite/`. Breakpoints can _only be set in test code_, meaning any code in the `e2e/out/` folder.
-
-Breakpoints set, go to the _Run and Debug_ pane in VS Code and run the Integration Tests configuration.
-
-### Debugging integration tests for the browser version
-
-Like [debugging integration tests](#debugging-integration-tests), do this when you want to debug the tests themselves rather than functionality. The web integration tests compile to in `web/src/suite/`.
-
-Set breakpoints in the compiled output (`web/dist/suite/index.js`).
-
-At time of writing you may have to set the breakpoints after the debugger has attached. I've had the best success rate clicking repeatedly to set the breakpoint.
+The best place to get started is [the guide for new contributors](https://wkillerud.github.io/some-sass/contributing/new-contributors.html).
 
 ## Conventional commits
 
@@ -157,10 +13,9 @@ Two assets are published:
 - The language server is published to npm
 - The VS Code extension is published to Visual Studio Marketplace and Open VSX
 
-Keep both in mind when deciding whether a change is a patch, minor or major release.
-
 | Commit message                                                                                                                            | Release type                                                                                                                                                         |
 | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `docs: added a guide for configuring sublime text`                                                                                        | Patch. Bugfix release, updates for runtime dependencies.                                                                                                             |
 | `fix: update css-languageservice`                                                                                                         | Patch. Bugfix release, updates for runtime dependencies.                                                                                                             |
 | `feat: add support for show keyword in forward`                                                                                           | Minor. New feature release.                                                                                                                                          |
 | `refactor: remove reduntant options for latest language version`<br><br>`BREAKING CHANGE: The scanImportedFiles option has been removed.` | Major. Breaking release, like removing an option or changing `engines` version. <br /> (Note that the `BREAKING CHANGE: ` token must be in the footer of the commit) |

README.md

@@ -1,15 +1,48 @@
 # Some Sass
 
-In this repo you'll find:
+Some Sass is a [language server extension][langext] for [Visual Studio Code][vscode]. It brings improved code suggestions, documentation and code navigation for [SCSS][scss].
 
-- the [Some Sass](./vscode-extension#readme) extension for VS Code
-- the [SCSS language server that powers it](./packages/language-server#readme)
+Some features include:
 
-The language server is [published independently to npm](https://www.npmjs.com/package/some-sass-language-server), and can be used with any editor that has a [language server protocol (LSP)](https://microsoft.github.io/language-server-protocol/) client.
+- Full support for [`@use`][use] and [`@forward`][forward], including aliases, prefixes and hiding.
+- Workspace-wide code navigation and refactoring, such as Rename Symbol.
+- Rich documentation through [SassDoc][sassdoc].
+- Language features for [`%placeholders`][placeholder], both when using them and writing them.
 
-## Editors with clients
+![](./docs/src/images/highlight-reel.gif)
+
+## Get the extension
+
+You can find the extension here:
+
+- On the [Visual Studio Code Marketplace][vsmarketplace].
+- On the [Open VSX Registry][openvsx].
+- In the [Releases section on GitHub][ghreleases].
+
+See the User guide section to learn more about what the extension can do.
+
+## Some Sass Language Server
+
+Some Sass is also a language server using the [Language Server Protocol (LSP)][lsp].
+
+The language server is [published on npm][npm], and can be used with any editor that has an LSP client. See [Getting started](./language-server/getting-started.md) to learn more.
+
+### Editors with clients
 
 The language server has clients for
 
 - [Visual Studio Code](./vscode-extension#readme)
 - [Neovim](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#somesass_ls)
+
+[lsp]: https://microsoft.github.io/language-server-protocol/
+[npm]: https://www.npmjs.com/package/some-sass-language-server
+[scss]: https://sass-lang.com/documentation/syntax/
+[use]: https://sass-lang.com/documentation/at-rules/use/
+[forward]: https://sass-lang.com/documentation/at-rules/forward/
+[langext]: https://code.visualstudio.com/api/language-extensions/language-server-extension-guide
+[sassdoc]: http://sassdoc.com
+[placeholder]: https://sass-lang.com/documentation/style-rules/placeholder-selectors/
+[vscode]: https://code.visualstudio.com/
+[vsmarketplace]: https://marketplace.visualstudio.com/items?itemName=SomewhatStationery.some-sass
+[openvsx]: https://open-vsx.org/extension/SomewhatStationery/some-sass
+[ghreleases]: https://github.com/wkillerud/some-sass/releases

docs/src/README.md

@@ -1,3 +1,47 @@
 # Some Sass
 
-Hello, World!
+Some Sass is a [language server extension][langext] for [Visual Studio Code][vscode]. It brings improved code suggestions, documentation and code navigation for [SCSS][scss].
+
+Some features include:
+
+- Full support for [`@use`][use] and [`@forward`][forward], including aliases, prefixes and hiding.
+- Workspace-wide code navigation and refactoring, such as Rename Symbol.
+- Rich documentation through [SassDoc][sassdoc].
+- Language features for [`%placeholders`][placeholder], both when using them and writing them.
+
+![](./images/highlight-reel.gif)
+
+## Get the extension
+
+You can find the extension here:
+
+- On the [Visual Studio Code Marketplace][vsmarketplace].
+- On the [Open VSX Registry][openvsx].
+- In the [Releases section on GitHub][ghreleases].
+
+See the User guide section to learn more about what the extension can do.
+
+## Some Sass Language Server
+
+Some Sass is also a language server using the [Language Server Protocol (LSP)][lsp].
+
+The language server is [published on npm][npm], and can be used with any editor that has an LSP client. See [Getting started](./language-server/getting-started.md) to learn more.
+
+## Navigating the docs
+
+To navigate between pages you can click the arrow buttons, press the left and right arrow keys on your keyboard, or use the sidebar menu.
+
+To search click the magnifying class icon to the top left or press `s` on your keyboard.
+
+[lsp]: https://microsoft.github.io/language-server-protocol/
+[npm]: https://www.npmjs.com/package/some-sass-language-server
+[scss]: https://sass-lang.com/documentation/syntax/
+[use]: https://sass-lang.com/documentation/at-rules/use/
+[forward]: https://sass-lang.com/documentation/at-rules/forward/
+[langext]: https://code.visualstudio.com/api/language-extensions/language-server-extension-guide
+[sassdoc]: http://sassdoc.com
+[placeholder]: https://sass-lang.com/documentation/style-rules/placeholder-selectors/
+[vscode]: https://code.visualstudio.com/
+[vsmarketplace]: https://marketplace.visualstudio.com/items?itemName=SomewhatStationery.some-sass
+[openvsx]: https://open-vsx.org/extension/SomewhatStationery/some-sass
+[ghreleases]: https://github.com/wkillerud/some-sass/releases