Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: revise install section #1090

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

docs: revise install section #1090

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d3420d8
docs: revise install section
SylvanFranklin Dec 29, 2024
452b706
fix: typos
SylvanFranklin Dec 30, 2024
8f44e30
docs: reformat
Myriad-Dreamin Dec 31, 2024
f48b790
docs: fix words and markers
Myriad-Dreamin Dec 31, 2024
1380a37
docs: fix install section
SylvanFranklin Jan 3, 2025
733afee
docs: revise preview section
SylvanFranklin Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 66 additions & 98 deletions docs/tinymist/frontend/neovim.typ
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,20 @@

#show: book-page.with(title: "Tinymist Neovim Extension")

Run and configure tinymist in Neovim for Typst.
Run and configure `tinymist` in Neovim with support for all major distros and package managers.

== Features
<features>
See #link("https://github.com/Myriad-Dreamin/tinymist#features")[Tinymist Features] for a list of features.
== Feature Integration
- *LSP* (completion, definitions, etc.)
- *Folding Ranges* supported with #link("https://github.com/kevinhwang91/nvim-ufo")[ufo.]
- *Code Formatting* with #link("https://github.com/Enter-tainer/typstyle/")[typstyle] or #link("https://github.com/astrale-sharp/typstfmt")[typstfmt (deprecated).]
Eric-Song-Nop marked this conversation as resolved.
Show resolved Hide resolved
- *Live Web Preview* with #link("https://github.com/chomosuke/typst-preview.nvim")[typst-preview.]

#include "common-finding-executable.typ"

- (Recommended) Stable versions available via #link("https://github.com/williamboman/mason.nvim")[mason.nvim];.
#note-box[
Work for full parity for all `tinymist` features is underway. This will include: exporting to different file types, template preview, and multifile support. Neovim integration is behind VS Code currently but should be caught up in the near future.
]

== Installation
- (Recommended) #link("https://github.com/williamboman/mason.nvim")[mason.nvim];.
```lua
{
"williamboman/mason.nvim",
Expand All @@ -22,122 +26,86 @@ See #link("https://github.com/Myriad-Dreamin/tinymist#features")[Tinymist Featur
},
}
```
- Or manually:

== Setup

This section shows you a minimal way to setup tinymist in #link("https://www.lazyvim.org/")[LazyVim]. We also have some tips for users of other distros.

// todo: heading link support
Please see #md-alter(link(<neovim-extra-settings>)[Extra Settings], () => link("#extra-settings")[Extra Settings]) for more configuration.

=== Setup for #link("https://www.lazyvim.org/")[LazyVim]
#include "common-finding-executable.typ"

Copy or merge the two files to corresponding paths into `~/.config/nvim/`.

- #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/config/autocmds.lua")[Autocmds file] will help associate the `.typ` file extension with the `typst` filetype.
- #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/plugins/tinymist.lua")[Plugin file] will help start tinymist for buffers with the `typst` filetype.

Then, check and restart Neovim.
== Configuration
Myriad-Dreamin marked this conversation as resolved.
Show resolved Hide resolved
- With `lspconfig`:
```lua
require("lspconfig")["tinymist"].setup {
settings = {
Eric-Song-Nop marked this conversation as resolved.
Show resolved Hide resolved
tinymist = {
settings = {
formatterMode = "typstyle",
exportPdf = "onType",
semanticTokens = "disable"
-- ...
},
},
}
}
```

=== Setup for #link("https://github.com/AstroNvim")[AstroVim]
- Or with `Coc.nvim`:

AstroNvim now uses tinymist by default. Please check the #link("https://github.com/AstroNvim/astrocommunity/tree/main/lua/astrocommunity/pack/typst")[setup script].
```json
{
"languageserver": {
"tinymist": {
"command": "tinymist",
"filetypes": ["typst"],
"settings": { ... }
}
}
}
```
- Or finally with the builtin lsp protocol:

=== Setup for #link("https://github.com/neoclide/coc.nvim")[coc.nvim]
```lua
vim.lsp.config['tinymist'] = {
cmd = {'tinymist'},
filetypes = {'typst'}
settings = {
-- ...
}
}
```

You can edit the `coc-settings.json` by executing `:CocConfig`:
For a full list of available settings see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration].

```json
{
"languageserver": {
"tinymist": {
"command": "tinymist",
"filetypes": ["typst"],
"settings": { ... }
}
}
}
```
== Formatting

== Tips
<tips>
=== Working with Multiple-File Projects
<working-with-multiple-file-projects>
The solution is a bit internal, which should get further improvement, but you can pin a main file by command.
Either `typstyle` or `typstfmt`. Both are now included in `tinymist`, you can select the one you prefer with:

```lua
-- pin the main file
vim.lsp.buf.execute_command({ command = 'tinymist.pinMain', arguments = { vim.api.nvim_buf_get_name(0) } })
-- unpin the main file
vim.lsp.buf.execute_command({ command = 'tinymist.pinMain', arguments = { nil } })
formatterMode = "typstyle"
```

There is also a plan to support multiple-file projects with a workspace configuration, but I don’t know whether it is Neovim’s way, so it needs further discussion.
== Preview

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if the pinMain part should be removed, as what I knew was that main file is more useful than just for preview, but I am sure that there won't be a workspace configuration anymore.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm honestly not sure what people mean when they have problems with the pin main and multi files. Tinymist seems to work fine for me across different files no problem. We could ask someone who complained about it

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New issue regarding this: #1103

Copy link
Owner

@Myriad-Dreamin Myriad-Dreamin Jan 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is used for working on multiple-files projects. Supposed having main.typ and you switch to chapter2.typ, you should expect that the language server still response according to main.typ as the main file. Note, vscode users usually don't use this functionality directly. When we preview a file, the file is requested to pin as main by the vscode extension.

#note-box[
`tinymist.pinMain` is a stateful command, and tinymist doesn't remember it between sessions (closing and opening the editor).
]
There is work in progress to integrate #link("https://github.com/chomosuke/typst-preview.nvim")[typst-preview.nvim] directly into `tinymist`. In the meantime you can find can find installation and configuration instructions on that repo. This should be a shortterm solution.
Eric-Song-Nop marked this conversation as resolved.
Show resolved Hide resolved

== Troubleshooting
<troubleshooting>
=== tinymist does not start on creating/opening files
<tinymist-does-not-start-on-creatingopening-files>
First, please check that tinymist starts when manually setting the filetype.

```
:set filetype=typst
```
Generally you can find in depth information via the `:mes` command. `:checkhealth` and `LspInfo` can also provide valuable information. Tinymist also creates a debug log that is usually at `~/.local/state/nvim/lsp.log`. Reporting bugs is welcome.

If tinymist starts, that means you have not made correct association between the file extension and filetype. There should be some error messages related to this in your lspconfig.

Please associate the `.typ` file extension with the `typst` filetype to start tinymist on file create/open events.

```shell
autocmd BufNewFile,BufRead *.typ setfiletype typst
```
=== tinymist not starting when creating/opening files
<tinymist-does-not-start-on-creatingopening-files>

== Extra Settings
<neovim-extra-settings>
=== Configuring Language Server
<neovim-configuring-language-server>
To configure the language server, you can edit the `opts.servers.tinymist.settings`. For example, if you want to export to PDF on typing and output files in `$root_dir/target` directory:
This is most commonly due to nvim not recognizing the `.typ` file extension as a `typst` source file. In most cases is can be resolved with:

```lua
return {
-- add tinymist to lspconfig
{
"neovim/nvim-lspconfig",
opts = {
servers = {
tinymist = {
settings = {
exportPdf = "onType",
outputPath = "$root/target/$dir/$name",
}
},
},
},
},
}
```typ
:set filetype=typst
```

See #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration] for references.

=== Configuring Folding Range for Neovim Client
<configuring-folding-range-for-neovim-client>
Enable LSP-based folding range with `kevinhwang91/nvim-ufo`:
In older versions of neovim an autocommand may be necessary.

```lua
return {
{ -- configure language servers
"neovim/nvim-lspconfig",
dependencies = "kevinhwang91/nvim-ufo", -- enable LSP-based folds
},
}
```vim
autocmd BufNewFile,BufRead *.typ setfiletype typst
```

You can copy or merge #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/plugins/lsp-folding.lua")[lsp-folding.lua] to corresponding paths into `~/.config/nvim/` and restart Neovim.

== Contributing
<contributing>
You can submit issues or make PRs to #link("https://github.com/Myriad-Dreamin/tinymist")[GitHub];.
Loading