[#75288] 17.5 Macros updates https://community.openproject.org/wp/75288 (#23486)

* [#75288] 17.5 Macros updates https://community.openproject.org/wp/75288 [#75288] 17.5 Macros updates https://community.openproject.org/wp/75288 * [DOCU-823] 17.5 Macros updates https://community.openproject.org/wp/DOCU-823 [DOCU-823] 17.5 Macros updates https://community.openproject.org/wp/DOCU-823 * [DOCU-823] 17.5 Macros updates https://community.openproject.org/wp/DOCU-823 [DOCU-823] 17.5 Macros updates https://community.openproject.org/wp/DOCU-823 * Apply suggestion from @MayaBerd * Apply suggestion from @MayaBerd * update * Apply suggestion from @MayaBerd --------- Co-authored-by: Maya Berdygylyjova <MayaBerd@users.noreply.github.com>
2026-06-13 19:20:00 +00:00 · 2026-06-03 07:49:42 +02:00
parent 367d536a5e
commit dcc42f4c03
6 changed files with 35 additions and 23 deletions
@@ -158,4 +158,7 @@ Wiki systems contain all the answers !#42

 ### Autocompletion for work packages

-For work packages, typing # will open an autocompleter for visible work packages. This means when you type e.g. #3 or #Market, a list of work packages matching the description will be shown. Then you can either continue typing or choose a work package from the list.
+For work packages, typing `#` will open an autocompleter for visible work packages. This means when you type e.g. #3 or #Market, a list of work packages matching the description will be shown. Then you can either continue typing or choose a work package from the list.
+
+> [!TIP]
+> To show more details when linking a work package, type either  `##` or `###` followed by the work package ID, subject, type or a keyword.
@@ -116,6 +116,9 @@ Starting with OpenProject 13.0 you can add emojis to all text editors. Type a co

 ![openproject_user_guide_wp_comment_emojis](openproject_user_guide_wp_comment_emojis.png)

+### Linking work packages
+To learn more about how to link work packages within the text editor, please consult this page [Rich text editor in OpenProject](../../wysiwyg/).
+
 ## Attach files to work packages

 > [!IMPORTANT]
@@ -35,13 +35,13 @@ Instead of creating a new paragraph with Enter, you can also press `SHIFT+Enter`

 Create hyperlinks by pressing the tool-bar (optionally with some selected text), or by pressing `CTRL+k` to open a popup to enter the link here.

-### Widgets and Newlines
+### Widgets and newlines

 CKEditor uses widgets to display block elements such as images, tables, and other elements that are not inline. You can select most widgets by pressing on them - The only exception to that is the table widget, it has a little select knob at the top left to select the entire table.

 When you have a widget selected, you can remove or cut it. You can create a newline below it by selecting the widget and pressing `ENTER` or `↓ (ARROW DOWN)`, or a newline above it by pressing `SHIFT+enter` or `↑ (ARROW UP)`. This is especially needed when the widget is the first or last element on the page to insert a line below or above it.

-### Code Blocks
+### Code blocks

 As CKEditor5 currently does not provide support for code blocks, OpenProject can display, but not edit code blocks within the CKEditor instance. A code block can be edited through a modal window within a `CodeMirror` editor instance. This has the advantage of providing syntax highlighting and code sensing ([for supported languages](https://codemirror.net/mode/)).

@@ -85,7 +85,7 @@ On top of that, OpenProject adds the following shortcut:
 OpenProject has supported macros on textile formatted pages and continues to do so with the WYSIWYG editor. Note that macros are not expanded while editing the page, instead, a placeholder is shown.

 You can find the macros here in the text editor:
-![Macros text editor](image-20201109183018255.png)
+![Macros text editor](openproject_user_guide_macros.png)

 ### Table of contents

@@ -113,24 +113,24 @@ Use it to embed views in other pages, create reporting of multiple results, or t

 As with the textile formatting syntax, you can link to other resources within OpenProject using the same shortcuts as before. Create links to a:

-| **Link target**                                               | Usage example                                 |
-|---------------------------------------------------------------|-----------------------------------------------|
-| Wiki page                                                     | `[[Wiki page]]`                               |
-| Wiki page with separate link name                             | `[[Wiki page\|The text of the link]]`         |
-| Wiki page in the Sandbox project                              | `[[Sandbox:Wiki page]]`                       |
-| Work package with ID12                                        | `#12`                                         |
-| Work package with ID 12 with subject and type                 | `##12`                                        |
-| Work package with ID 12 with subject, type, status, and dates | `###12`                                       |
-| Version by ID or name                                         | `version#3`,  `version:"Release 1.0.0"`       |
-| Project by ID/name                                            | `project#12` , `project:"My project name"`    |
-| Attachment by filename                                        | `attachment:filename.zip`                     |
-| Meeting by ID/name                                            | `meeting#12` , `meeting:"My meeting name"`    |
-| Document by ID/name                                           | `document#12` , `document:"My document name"` |
-| User by ID or login                                           | `user#4` , `user:"johndoe"`                   |
-| Forum message by ID                                           | `message#1218`                                |
-| Repository revision 43                                        | `r43`                                         |
-| Commit by hash                                                | `commit:f30e13e4`                             |
-| Source file in the repository                                 | `source:"some/file"`                          |
+| **Link target**                                       | Usage example                                 |
+| ----------------------------------------------------- | --------------------------------------------- |
+| Wiki page                                             | `[[Wiki page]]`                               |
+| Wiki page with separate link name                     | `[[Wiki page\|The text of the link]]`         |
+| Wiki page in the Sandbox project                      | `[[Sandbox:Wiki page]]`                       |
+| Work package with ID12                                | `#12`                                         |
+| Work package with ID 12 with subject and type         | `##12`                                        |
+| Work package with ID 12 with subject, type and status | `###12`                                       |
+| Version by ID or name                                 | `version#3`,  `version:"Release 1.0.0"`       |
+| Project by ID/name                                    | `project#12` , `project:"My project name"`    |
+| Attachment by filename                                | `attachment:filename.zip`                     |
+| Meeting by ID/name                                    | `meeting#12` , `meeting:"My meeting name"`    |
+| Document by ID/name                                   | `document#12` , `document:"My document name"` |
+| User by ID or login                                   | `user#4` , `user:"johndoe"`                   |
+| Forum message by ID                                   | `message#1218`                                |
+| Repository revision 43                                | `r43`                                         |
+| Commit by hash                                        | `commit:f30e13e4`                             |
+| Source file in the repository                         | `source:"some/file"`                          |

 To avoid processing these items, preceding them with a bang `!` character such as `!#12` will prevent linking to a work package with ID 12.

@@ -144,6 +144,12 @@ To avoid processing these items, preceding them with a bang `!` character such a

 For work packages and users, typing `#` or `@` will open an autocomplete dropdown for visible work packages and users, respectively.

+![Autocomplete dropdown for visible work packages](openproject_user_guide_macros_autocompletion.png)
+![Link a work package using an hash](openproject_user_guide_workpackage_mentions.png)
+
+> [!TIP]
+> To show more details when linking a work package, type either  `##` or `###` followed by the work package ID, subject, type or a keyword.
+
 ## Embedding of work package attributes and project attributes

 > [!NOTE]
@@ -172,7 +178,7 @@ Example:

 **Linking to the assignee of work package with subject "Project start"**: `workPackageValue:"Project start":assignee`

-> [!NOTE]
+> [!IMPORTANT]
 > Referencing a work package by subject results in only looking for work packages with that given subject in the current project (if any).
 > If you need to cross-reference work packages, use their ID to pinpoint the work package you want to reference.
 > We recommend against using subjects as references, as they are not updated when the referenced subject changes.