deploy: e75ea7c

docs/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 17ed1cb56dc0a909079d400917b1212a
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_sources/collaboration.md.txt

@@ -0,0 +1,31 @@
+# Collaboration
+
+MyST allows multiple users to edit a document simultaneously.
+You can see how many users are editing a document by looking at their avatars in the [topbar](topbar.md).
+A username and a color are assinged to each user.
+
+You can see the cursors of other users in their respectful colors in the editor with their usernames attached.
+Your cursor will be a simple vertical bar.
+
+Whenever someone makes a selection it will also be visible.
+
+## Connection Issues
+
+:::{figure-md} connection-error
+![Connection Error](./assets/conn-error.png)
+
+Connection Error
+:::
+
+Should you run into connection problems, an error will be displayed and the editor will be locked.
+In such case, please check your internet connection and restart the editor.
+If you do have internet access and the issue still continues, the collaboration server might be offline.
+
+```{warning}
+Changes made in the editor while offline are lost, but a connectivity error should lock the editor and prompt you to restart.
+```
+
+## Other Collaborative Features
+
+There are many more MyST features aimed at collaboration.
+For more information refer to the [](comments.md) and [](rich-links.md) sections.

docs/_sources/comments.md.txt

@@ -0,0 +1,152 @@
+# Comments
+
+To leave feedback for other users collaborating on a document without changing the document text itself, you can leave comments.
+
+## Adding a Comment
+
+:::{figure-md} add-comment
+![Add Comment](./assets/comment-add.png)
+
+Add comment
+:::
+
+To add a comment, hover your cursor over the editor gutter (to the left of line numbers) on the line you want to comment on.
+This should make the comment icon appear.
+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.
+All new comments will be expanded as well.
+
+## Collaborating on a Comment
+
+:::{figure-md} multiple-authors
+![Multiple comment authors](./assets/comment.png)
+
+Multiple comment authors
+:::
+
+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).
+
+## Moving Comments
+
+As new lines are added above a line with a comment, the comment will move with its original line. 
+Pressing `enter` at the beginning of a commented line will also move it downwards.
+
+```{warning}
+Pressing backspace at the beginning of a commented line will delete the comment.
+```
+
+You can also move comments via drag and drop. To move a comment to another line, drag its icon to the left of the desired line's number.
+
+```{tip}
+Moving a comment onto another comment will append its contents.
+```
+
+## Deleting Comments
+
+```{warning}
+Deleting a comment will delete input from all users, not just your text.
+```
+
+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
+- Hover over the comment icon and press the delete button
+- Press the delete button in the resolved comments view (details in the [](#resolving-comments) section).
+
+## Resolving Comments
+
+MyST Editor offers a comment resolution functionality.
+
+To resolve a comment, hover over its icon and click the resolve button.
+This will move it to the `Resolved Comments` view in the [topbar](topbar.md) where it will be accessible.
+Click the `Resolved Comments` button to see it.
+Such comments are annotated with the following information:
+
+- Comment author
+- User who resolved the comment
+- Comment resolution time
+- Origin text line
+
+You can access more options by hovering over the `...` button in the top right of a comment.
+
+:::{figure-md} resolved-comment
+![Resolved Comment](./assets/resolved-comment.png)
+
+Resolved comment
+:::
+
+### Restoring Comments
+
+After a comment is resolved, it will keep track of the line it was attached to.
+Should the text in the line or its line number change, it will be reflected in this view.
+You can bring back a comment to the editor by clicking the restore button in the `...` menu.
+
+In case there is another comment in a resolved comment's line, the restore button will read `RESTORE AND MERGE`, indicating that the original line is occupied.
+When you press this button, the resolved comment will be added to the bottom of the newer comment.
+
+:::{figure-md} merge-comments
+![Merge Comments](./assets/comment-occupied.png)
+
+Merging comments
+:::
+
+#### Orphaned Comments
+
+:::{figure-md}
+![Orphaned Comment](./assets/comment-orphaned.png)
+
+Orphaned comment
+:::
+
+If a resolved comment does not have a line number next to it or the text of the commented line is crossed out, the line the comment was assigned to has been deleted.
+Such a comment is considered `orphaned`.
+If you try to restore such a comment, it will be added to the last line of the document.
+From there you can move it wherever you want.
+
+```{warning}
+Applying a document template to a document with resolved comments, will make all of them `orphaned`.
+```
+
+## Suggestions
+
+:::{figure-md} suggest-change
+![Suggest Change](./assets/suggestion.png)
+
+Change suggestion
+:::
+
+You can suggest changes to a line in a comment.
+To do so you can use the following syntax within the comment:
+
+```md
+|<text to replace> -> <replacement>|
+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.
+
+```{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).
+```
+
+````{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.
+
+```md
+eg. |something| - this will highlight the word something
+```
+````

docs/_sources/index.md.txt

@@ -0,0 +1,12 @@
+# {{project}}
+
+```{toctree}
+:maxdepth: 2
+
+introduction
+topbar
+collaboration
+mermaid
+rich-links
+comments
+```

docs/_sources/introduction.md.txt

@@ -0,0 +1,18 @@
+# Introduction
+
+![MyST Editor](./assets/myst.png)
+
+MyST Editor is a collaborative Markdown editor. 
+It uses [MyST](https://mystmd.org/) - a Markdown flavor intended for technical documentation.
+For a general introduction to the MyST syntax, please refer to the [MyST Markdown Guide](https://mystmd.org/guide/quickstart-myst-markdown).
+The goal of this manual is to introduce the editor's features and describe how to use them effectively.
+
+This manual consists of the following chapters:
+
+- [](topbar.md) - discusses the elements of the editor topbar
+- [](collaboration.md) - discusses functionalities related to collaborative edition
+- [](mermaid.md) - discusses support for [Mermaid diagrams](https://mermaid.js.org/)
+- [](rich-links.md) - introduces editor-specific syntax for linking to external entities
+- [](comments.md) - showcases how to use comment functionalities
+
+To try MyST Editor, go to its [current demo](https://antmicro.github.io/myst-editor/).

docs/_sources/mermaid.md.txt

@@ -0,0 +1,21 @@
+# Mermaid Diagrams
+
+MyST allows users to include various diagrams in their documents using the [Mermaid](https://mermaid.js.org/) library.
+For an explanation on how to create diagrams, refer to the `Diagram Syntax` section of the [Mermaid Documentation](https://mermaid.js.org/intro/).
+Here is an example graph in MyST:
+
+````md
+```mermaid
+  graph TD;
+      A-->B;
+      A-->C;
+      B-->D;
+      C-->D;
+```
+````
+
+:::{figure-md} mermaid-graph
+![Connection Error](./assets/mermaid.png)
+
+Mermaid Graph
+:::

docs/_sources/rich-links.md.txt

@@ -0,0 +1,53 @@
+# Rich Links
+
+MyST editor offers convenient links for integrating with parts of your chosen infrastructure.
+Below we provide examples of the functionality integrated with GitHub's infrastructure.
+
+You can test these functionalities in the [MyST Editor demo](https://antmicro.github.io/myst-editor/).
+
+## Issues
+
+You can link to an issue by using a issue number and optionally a repository name. 
+Without a repository name, the editor will assume the same repo MyST is deployed to.
+
+```md
+#<issue number>
+eg. #11111
+
+<repo>#<issue number>
+eg. github/docs#11111
+```
+
+## Pull Requests
+
+You can link to a pull request by the PR number and optionally the git repository name:
+
+```md
+!<PR number>
+eg. !213
+
+<repo>!<PR number>
+eg. antmicro/myst-editor!2
+```
+
+## Mentions
+
+You can mention another user, which will render a link to their profile.
+
+```md
+@<username>
+eg. @jdoe
+```
+
+## 'Say' phrase
+
+You can put your username next to a string of text within an inline code block by using the `{say}` custom role:
+
+```md
+{say}`<text>`
+eg. {say}`something` -> will render as: <username> says: 'something'
+```
+
+## Refreshing Links
+
+To refresh all rich links within a document, click the `Refresh issue links` button in the [left section of the topbar](topbar.md#left-side-buttons).

docs/_sources/topbar.md.txt

@@ -0,0 +1,58 @@
+# Topbar
+
+The editor topbar contains information and buttons.
+
+## Left side buttons
+
+:::{figure-md} left-side-buttons
+![Left side buttons](./assets/left-side.png)
+
+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
+- `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
+- `Templates` - applies a template for projects that support the feature.
+
+  ```{warning}
+  Applying a template while there is already text in the document will replace all the text with the template. 
+  You can undo this action, however any comments in the document will be removed.
+  ```
+
+## Document Name
+
+Displays the name of the document, for example the name of an issue, documentation page or meeting.
+
+## User Avatars
+
+Avatars of users currently editing a document will be displayed in the topbar. 
+With several collaborators, only a couple avatars are displayed with an indicator of how many more are editing.
+
+```{tip}
+Hovering over an avatar or the "more users" indicator reveals usernames.
+```
+
+## Custom Buttons
+
+Depending on the configuration of the editor, you can add more buttons.
+
+## View Mode Buttons
+
+:::{figure-md} view-mode-buttons
+![View Mode Buttons](./assets/view-btns.png)
+
+View Mode buttons
+:::
+
+MyST editor has several view modes, activated with buttons on the right side of the topbar, as illustrated in {numref}`view-mode-buttons`.
+Starting from the left, the buttons serve the following functions:
+
+- `Source` - only show the Markdown source code
+- `Preview` - only show a rendered document preview
+- `Dual Pane` - **(default)** - show Markdown on the left and a rendered preview on the right
+- `Diff View` - show changes made to the document
+- `Resolved Comments` - show resolved comments, for more information see [Resolving Comments](comments.md#resolving-comments).