Consider modernising the documentation framework.

[rchl]

Main reason I'd consider switching current documentation framework out is that the markup handling is a bit different from (github) markdown.

We could use vuepress (example https://docs.sublimetext.io/guide/) or Nuxt content (example https://axios.nuxtjs.org/).

[jwortmann]

I think the version of MkDocs that we use with readthedocs is not the latest version available, because I have seen some differences in code block highlighting when building the docs locally, compared to the current LSP docs website. According to the documentation, the version used can be set via an admin dashbord, or alternatively via a configuration file readthedocs.yml that we apparently don't use currently.

And the formatting from MkDocs could then probably configured via extensions that are to be listed in the mkdocs.yml file, for example use more highlighting languages for code blocks, or we could add admonitions like this.

I must say that the documentation at https://docs.sublimetext.io/guide/ looks pretty nice, though.

[rwols]

Honestly, what’s wrong with a few wiki pages here on GitHub itself, or a few github pages?

[rwols]

Oh, I suppose not everyone has a github account. You need one to read the wiki pages I think? Maybe github pages are accessible for outsiders without a github account.

[jfcherng]

You need one to read the wiki pages I think?

No. Tested with Chrome incognito mode.

[rchl]

Isn't github pages just deployment and hosting for your pages? You still need to generate pages from markdown and stuff if you want something more fency. So that is not exclusive to using any documentation framework.

[rwols]

By the way, I'm looking into automating some of the documentation because there's a lot of repetition in the docs.

Something like this

```ts { "$schema": "sublime://Packages/LSP/docs/index-schema", "language_ids": { "bat": null, "shaderlab": { "name": "Shader", "selector": "source.glsl | source.essl", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/GLSL/OpenGL Shading Language (GLSL).sublime-syntax" } ] }, "php": { "name": "PHP", "selector": "source.php | embedding.php", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/PHP/PHP.sublime-syntax" } ] }, "go": { "name": "Go", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/Go/Go.sublime-syntax" } ] }, "html-ngx": { "name": "Ngx HTML", "selector": "text.html.ngx", "syntaxes": [ { "gh_repo": "princemaple/ngx-html-syntax", "syntax": "Packages/NgxHTML.sublime-syntax" } ] }, "svelte": { "name": "Svelte", "selector": "text.html.svelte", "syntaxes": [ { "gh_repo": "corneliusio/svelte-sublime", "syntax": "Packages/Svelte/Svelte.sublime-syntax" } ] }, "ruby": { "name": "Ruby", "selector": "source.ruby | text.html.ruby", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/Ruby/Ruby.sublime-syntax" }, { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/Rails/Ruby On Rails.sublime-syntax" } ] }, "javascript": { "name": "Javascript", "selector": "source.js", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/Javascript/Javascript.sublime-syntax" } ] }, "typescript": { "name": "Typescript", "selector": "source.ts", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/Typescript/Typescript.sublime-syntax" } ] }, "javascriptreact": { "name": "Javascript React", "selector": "source.jsx | source.js.react", "syntaxes": [ { "gh_repo": "SublimeHQ/Packages", "syntax": "Packages/Javascript/JSX.sublime-syntax" } ] } }, "language_servers": { "gopls": { "instructions": "install gopls", "languages": [ "go" ], "command": [ "gopls" ] }, "polymer": { "languages": [ "html", "css", "less", "scss" ] }, "intelephense": { "languages": [ "php" ], "plugin": "github.com/sublimelsp/LSP-intelephense" }, "vscode-css": { "languages": [ "css", "scss", "less" ], "plugin": "github.com/sublimelsp/LSP-css" }, "vscode-json": { "languages": [ "json", "jsonc" ], "plugin": "github.com/sublimelsp/LSP-json" }, "clangd": { "languages": [ "c", "cpp", "objective-c", "objective-cpp" ], "command": [ "clangd", "--log=error" ] }, "ccls": { "languages": [ "c", "cpp", "objective-c", "objective-cpp" ], "command": [ "ccls" ] }, "SourceKit": { "languages": [ "swift", "c", "cpp", "objective-c", "objective-cpp" ], "plugin": "github.com/sublimelsp/LSP-SourceKit" }, "OmniSharp": { "languages": [ "csharp", "cake" ], "plugin": "github.com/sublimelsp/LSP-OmniSharp" }, "PowershellEditorServices": { "languages": [ "powershell" ], "plugin": "github.com/sublimelsp/LSP-PowershellEditorServices" }, "ESLint": { "languages": [ "vue", "javascript", "javascriptreact", "typescript", "typescriptreact" ], "plugin": "github.com/sublimelsp/LSP-eslint" }, "typescript": { "languages": [ "javascript", "javascriptreact", "typescript", "typescriptreact" ], "plugin": "github.com/sublimelsp/LSP-typescript" }, "Vetur": { "languages": [ "vue" ], "plugin": "github.com/sublimelsp/LSP-vue" }, "TexLab": { "languages": [ "tex", "bibtex" ], "plugin": "github.com/sublimelsp/LSP-TexLab" }, "pyls": { "languages": [ "python" ], "plugin": "github.com/sublimelsp/LSP-pyls" }, "mspython": { "languages": [ "python" ], "command": [ "dotnet", "exec", "path/to/Microsoft.Python.Language.Server.dll" ] }, "svelte": { "languages": [ "svelte" ], "plugin": "github.com/sublimelsp/LSP-svelte" }, "angular": { "languages": [ "html-ngx" ], "plugin": "github.com/sublimelsp/LSP-angular" } } } ```

can be used to create the docs I think (and also recreate the default_clients dict).

[predragnikolic]

Whould you like the new documentation site to live inside this repo /docs folder or would you like the docs to be in a new repo?

[rwols]

Probably best if it's in another repo.

[rwols]

Keep in mind that most of our docs can be automated through a large json "index" file like described above. It would be a waste of time to write it all out manually.

[rwols]

You can also source all of the settings descriptions from the sublime-package.json file

[rwols]

The docs are now modernized for the ST4 version.