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 1 commit
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
184 changes: 74 additions & 110 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/")[typestyle] or #link("https://github.com/astrale-sharp/typstfmt")[typstfmt] (depreciated)
- *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,121 +26,81 @@ See #link("https://github.com/Myriad-Dreamin/tinymist#features")[Tinymist Featur
},
}
```

== 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]

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.

=== Setup for #link("https://github.com/AstroNvim")[AstroVim]

AstroNvim now uses tinymist by default. Please check the #link("https://github.com/AstroNvim/astrocommunity/tree/main/lua/astrocommunity/pack/typst")[setup script].

=== Setup for #link("https://github.com/neoclide/coc.nvim")[coc.nvim]

You can edit the `coc-settings.json` by executing `:CocConfig`:

```json
{
"languageserver": {
"tinymist": {
"command": "tinymist",
"filetypes": ["typst"],
"settings": { ... }
- Or manually:

#include "common-finding-executable.typ"

== Configuration
Myriad-Dreamin marked this conversation as resolved.
Show resolved Hide resolved
- With `lspconfig`
```lua
require("lspconfig")["tinymist"].setup {
settings = {
tinymist = {
settings = {
SylvanFranklin marked this conversation as resolved.
Show resolved Hide resolved
formatterMode = "typstyle",
exportPdf = "onType",
semanticTokens = "disable"
-- ...
},
},
},
}
}
}
```

== 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.

```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 } })
```
```

- Or with `Coc.nvim`

```json
{
"languageserver": {
"tinymist": {
"command": "tinymist",
"filetypes": ["typst"],
"settings": { ... }
}
}
}
```
- Or finally with the builtin lsp protocol

```lua
vim.lsp.config['tinymist'] = {
cmd = {'tinymist'},
filetypes = {'typst'}
settings = {
-- ...
}
}
```
For a full list of availible settings see #link("https://github.com/Myriad-Dreamin/tinymist/tree/main/editors/neovim/Configuration.md")[Tinymist Server Configuration].
Myriad-Dreamin marked this conversation as resolved.
Show resolved Hide resolved

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.
== Formatting
Install either `typststyle` or `typstfmt` either via source or via `Mason`. Then specify the formatter in your config
Myriad-Dreamin marked this conversation as resolved.
Show resolved Hide resolved

#note-box[
`tinymist.pinMain` is a stateful command, and tinymist doesn't remember it between sessions (closing and opening the editor).
]
```lua
formatterMode = "typstyle"
```
== Preview
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.
Copy link
Owner

Choose a reason for hiding this comment

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

I believe we have introduced an announcement here that we will provide some plugin developed inside of tinymist repository, while we were only providing a sample plugin to integrate tinymist into LazyVim. I have a few questions:

  • What's the position of the new plugin? Does it only replace the typst-preview.nvim?
  • How do the replaced plugin authors think of it? Is it common or supported in (neo)vim community? Will they join or against to build an out-of-box new typst.nvim? We must at least discuss about it with chomosuke.

Copy link
Owner

@Myriad-Dreamin Myriad-Dreamin Dec 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

If we could, imo we should push patches or changes to existing plugins to not force people to leave their old settings but still get benefit from our work.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes I agree that sounds good. I was wondering at the status of all of that, good to know progress is underway. I am not sure on how that integration will work I was assuming you had some deal what that plugin author. To me it makes sense to not have an external preview tool when there is potential for the lsp to have that feature, but I think the whole issue requires discussion.


== 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. Tinymist also creates a debug log that is usually at `~/.local/state/nvim/lsp.log`
Myriad-Dreamin marked this conversation as resolved.
Show resolved Hide resolved

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.
=== tinymist not starting when creating/opening files
<tinymist-does-not-start-on-creatingopening-files>

Please associate the `.typ` file extension with the `typst` filetype to start tinymist on file create/open events.
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:

```shell
autocmd BufNewFile,BufRead *.typ setfiletype typst
```
```typ
:set filetype=typst
```

== 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:
In older versions of neovim an autocommand may be necessary.

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

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`:

```lua
return {
{ -- configure language servers
"neovim/nvim-lspconfig",
dependencies = "kevinhwang91/nvim-ufo", -- enable LSP-based folds
},
}
```

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.
```vim
autocmd BufNewFile,BufRead *.typ setfiletype typst
```

== Contributing
<contributing>
Expand Down
Loading