[#72158] Update README and User Manual

.ci.yml

@@ -37,13 +37,19 @@ build-docs:
   when: manual
   image: $CI_DOCS_DOCKER_IMAGE
   tags: ["ace-x86_64"]
+  before_get_sources:
+    - apt-get update
+    - apt-get install python3-venv python3-pip python3 -y
   before_script:
     - cd docs
+    - python3 -m venv .venv
+    - source .venv/bin/activate
     - pip3 install -r requirements.txt
   script:
     - cd docs
+    - source .venv/bin/activate
     - |
-      printf "\nfrom antmicro_sphinx_utils.defaults import relative_to_git\nfrom pathlib import Path\ngit_path = relative_to_git(Path(__file__).parent)\nhtml_css_files = ['$MYST_LOADER_REPOSITORY/MystEditor.css']\nhtml_js_files = [(f'$MYST_LOADER_REPOSITORY/myst_loader.js?docs-root={str(git_path).replace(\"/\", \"%%2F\")}', { 'type': 'module' })]" >> source/conf.py
+      printf "\nfrom antmicro_sphinx_utils.defaults import relative_to_git\nfrom pathlib import Path\ngit_path = relative_to_git(Path(__file__).parent)\nhtml_css_files = ['$MYST_LOADER_REPOSITORY/MystEditor.css']\nhtml_js_files = [(f'$MYST_LOADER_REPOSITORY/myst_loader.js?fix=://&docs-root={str(git_path).replace(\"/\", \"%%2F\")}', { 'type': 'module' })]" >> source/conf.py
     - make html
     - cd ..
     - tar cf $CI_DOCS_ARCHIVE -C docs/build/html/ .

README.md

@@ -13,7 +13,7 @@ For an overview of the editor usage, see the [User Manual](https://antmicro.gith
 
 ## Demo
 
-A demo without the collaborative features is available [here](https://antmicro.github.io/myst-editor/).
+A demo of the editor is available [here](https://antmicro.github.io/myst-editor/).
 
 ## Main features
 
@@ -55,6 +55,13 @@ Using the buttons in the top-left, you can copy the rendered HTML or export the
 
 ![Copy Demo](./assets/export.png)
 
+### User settings
+
+Users can customize the editor with the settings dropdown.
+In the example below, we can see settings that allow for scrolling past the last line of the editor and autocompleting Markdown lists.
+
+![Settings Demo](./assets/settings.gif)
+
 ### Custom transforms
 
 The editor allows you to extend the standard Markdown syntax with custom transforms.
@@ -149,35 +156,41 @@ Here are the options you can pass to the MystEditor function:
 
 - `id` *(default: `crypto.randomUUID()`)* - this changes where the global state of an editor is stored, it is used when accessing `window.myst_editor` and is part of the CodeMirror parent DOM id
 - `name` *(default: "myst_editor_textarea")* - this will change the name of the textarea element which contains your markdown. Useful if you want the editor to be part of an HTML `form`.
-- `initialMode` *(default: "Both", possibleValues: "Source" | "Preview" | "Both")* - changes what is visible when you open the editor. By default, you will see a split view with the text editor and preview.
+- `additionalStyles` *(`CSSStylesheet` | `CSSStylesheet[]`)* - extra CSS stylesheets to customize the component
+- `title` - the document title displayed in the topbar. You can include Markdown links in here.
+- `mode` *(default: "Both", possibleValues: "Source" | "Preview" | "Both" | "Diff" | "Resolved")* - changes what is visible when you open the editor. By default, you will see a split view with the text editor and preview.
 - `initialText` *(default: "")* - initial Markdown text
 - `includeButtons` *(default: defaultButtons)* - An array of button definitions. A button definition is an object which has an `action: () => void` and either `icon` or `text`. As an example, a button could be defined as `{ text: "Button title", action: () => alert('clicked!') }`
 - `topbar` *(default: true)* - whether to show the topbar
 - `templateList` - path/url to a JSON file containing your document templates. For an example, see `public/linkedtemplatelist.json`.
-- `transforms` - [custom transforms](#custom-transforms)
-- `getAvatar` *(default: (login) => `https://secure.gravatar.com/avatar/${login}?s=30&d=identicon`)* - a function that returns the avatar for a given username
-- `getUserUrl` *(default: (login) => `#`)* - a function that returns the URL to the web page with the user's profile
-  It is used when an avatar is clicked.
 - `collaboration` - options related to live collaboration:
   - `enabled` *(default: false)*
+  - `commentsEnabled` *(default: false)* - enable basic comment functionality,
+  - `resolvingCommentsEnabled` *(default: false)* - enable resolving comments,
   - `wsUrl` *(example: ws://example:4444)* - URL of the websocket server
-  - `commentsEnabled` - enable basic comment functionality,
-  - `resolvingCommentsEnabled` - enable resolving comments,
   - `username`
-  - `room` - name of the room to join, users will see others in the same room
-  - `color` - color of the cursor seen by other users
-  - `hideUsernameDelay` *(default: 5000)* - milliseconds of inactivity after which the username attached to a remote cursor will be hidden
+  - `room` *(default: "0")* - name of the room to join, users will see others in the same room
+  - `color` *(default: "#ff0000")* - color of the cursor seen by other users
+  - `mode` *(default: "websocket")* - determines how the document will be synced. You can set it to `"local"` for testing without a server (using BroadcastChannel API)
 - `spellcheckOpts` - Configuration for the spellchecker. If the value is *null* or *false* then the spellchecker will be disabled.
   - `dict` *(default: "en_US")* - Name of the desired dictionary. For an example, see `public/dictionaries/en_US`.
   - `dictionaryPath` *(default: "/dictionaries")*  - Path to a folder with dictionaries. For an example, see `public/dictionaries/`.
+- `customRoles` - custom MyST roles. See [the demo HTML](./src/index.html) for examples.
+- `transforms` - [custom transforms](#custom-transforms)
+- `customDirectives` - custom MyST directives. See [the demo HTML](./src/index.html) for examples.
+- `getAvatar` *(default: (login) => `https://secure.gravatar.com/avatar/${login}?s=30&d=identicon`)* - a function that returns the avatar for a given username
+- `getUserUrl` *(default: (login) => `#`)* - a function that returns the URL to the web page with the user's profile
+  It is used when an avatar is clicked.
 - `backslashLineBreak` *(default: true)* - treat `\` as a line break even when it is at the end of a paragraph/block
-- `additionalStyles` *(`CSSStylesheet` | `CSSStylesheet[]`)* - extra CSS stylesheets to customize the component
+- `hideUsernameDelay` *(default: 5000)* - milliseconds of inactivity after which the username attached to a remote cursor will be hidden
 - `syncScroll` *(default: false)* - synchronize scrolling of the editor and preview in `Dual Pane` view mode.
   - > NOTE: This only works if you set a height limit on the editor parent element.
 - `unfoldedHeadings` *(`number?`)* - fold all but the given number of top level syntax nodes on startup.
   If the option is not set, nothing will be folded by default.
+- `mapUrl` *(default: (tag, url) => url)* - function used to map `href` and `src` attributes. Tag is the name of the HTML element and url is the source url you can transform.
 
 Also see [the demo HTML](./src/index.html) for an example on how you can set these options.
+Using `window.myst_editor` or the return value of the `MystEditor` function, you can modify these options at runtime.
 
 ## Myst Editor for Git
 

docs/source/comments.md

@@ -17,7 +17,7 @@ Click on the icon to create a comment.
 ## Toggling Comments
 
 Clicking on the comment icon can be used to hide/show a comment.
-By default when you load a document, all preexisting comments will be expanded.
+By default, when you load a document, all preexisting comments will be expanded.
 All new comments will be expanded as well.
 
 ## Collaborating on a Comment
@@ -28,11 +28,11 @@ All new comments will be expanded as well.
 Multiple comment authors
 :::
 
-Comments can span multiple lines and multiple users can participate in writing a single comment.
+Comments can span multiple lines, and multiple users can participate in writing a single comment.
 MyST Editor enables comment discussions through a concept of line authorship.
 Every line of a comment is highlighted in the color of the line's author.
 When you hover over a line, you can also see its author's avatar to the left of the comment.
-If you want to participate in a discussion, it is recommended to add a new line (for example at the end of a comment you want to reply to).
+If you want to participate in a discussion, it is recommended to add a new line (for example, at the end of a comment you want to reply to).
 
 ## Moving Comments
 
@@ -55,7 +55,7 @@ Moving a comment onto another comment will append its contents.
 Deleting a comment will delete input from all users, not just your text.
 ```
 
-In order to delete a comment you can:
+In order to delete a comment, you can:
 
 - Press backspace at the beginning of a commented line
 - Delete/cut a selection containing the commented line
@@ -125,7 +125,7 @@ Change suggestion
 :::
 
 You can suggest changes to a line in a comment.
-To do so you can use the following syntax within the comment:
+To do so, you can use the following syntax within the comment:
 
 ```md
 |<text to replace> -> <replacement>|
@@ -135,13 +135,21 @@ eg. |is -> was|
 This will cross out all the occurrences of such text within the line and place a suggested replacement next to them in the document.
 The suggestion will be colored after the color of the comment line it is in.
 Clicking the colored suggestion will apply it, which can be undone/redone.
-This will only apply one occurrence of the suggestion.
+This will only apply to one occurrence of the suggestion.
 
 ```{note}
 Suggestions only match against whole words/symbols. 
 If you want to match a certain occurrence of a word, try adding more context (more words/symbols around it).
 ```
 
+You can also suggest deleting a portion of text. To do this, simply leave the replacement after `->` blank:
+
+:::{figure-md} suggest-deletion
+![Suggest Deletion](./assets/suggest-del.png)
+
+Removal suggestion
+:::
+
 ````{tip}
 If you don't specify a replacement, the text between `||` will be highlighted. 
 This can be useful to bring attention to a section of a line.
@@ -150,3 +158,11 @@ This can be useful to bring attention to a section of a line.
 eg. |something| - this will highlight the word something
 ```
 ````
+
+To easily add suggestions, you can select some text from one line and click the button that appears near your selection:
+
+:::{figure-md} suggest-button
+![Suggest Button](./assets/suggest-btn.png)
+
+Add suggestion button
+:::

docs/source/index.md

@@ -5,6 +5,7 @@
 
 introduction
 topbar
+settings
 collaboration
 mermaid
 rich-links

docs/source/settings.md

@@ -0,0 +1,18 @@
+# Settings
+
+You can customize the editor by hovering over the settings icon in the left-side of the topbar and toggling various extra features:
+
+:::{figure-md} settings
+![Settings](./assets/settings.png)
+
+Settings dropdown
+:::
+
+Your settings will be saved in your browser for future editing sessions.
+
+## List of available settings
+
+- **Autocomplete Markdown** - automatically continue Markdown lists and blockquotes when pressing `Enter`. This will also speed up deleting list markers with the `Backspace` key.
+- **Autoclose brackets** - automatically place a closing bracket when the opening one is typed.
+- **Open links in new tabs** - links in the Preview will open in new tabs by default.
+- **Scroll past last line** - allows the editor to be scrolled past the last line.

docs/source/topbar.md

@@ -13,6 +13,7 @@ Left-side topbar buttons
 Starting from the left, the left side topbar visible in {numref}`left-side-buttons` includes the following buttons:
 
 - `Fullscreen` - toggles fullscreen editor mode
+- `Settings` - opens the [Settings](settings.md) dropdown
 - `Copy document as HTML` - copies the rendered document exported as HTML
 - `Refresh issue links` - re-renders all [rich links](rich-links.md) in the document
 - `Print to PDF` - save the rendered document as a PDF file or print it