diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-customize.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-customize.png new file mode 100644 index 000000000..be166190d Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-customize.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-empty-project.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-empty-project.png new file mode 100644 index 000000000..7489ad0c9 Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-empty-project.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-first-file.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-first-file.png new file mode 100644 index 000000000..6e0f00b81 Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-first-file.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-first-start.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-first-start.png new file mode 100644 index 000000000..e8a5e6cef Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-first-start.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-git.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-git.png new file mode 100644 index 000000000..30ebc94f9 Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-git.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-install-plugin-asciidoc.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-install-plugin-asciidoc.png new file mode 100644 index 000000000..dcd95f6c6 Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-install-plugin-asciidoc.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-tool-windows.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-tool-windows.png new file mode 100644 index 000000000..ff518a7e9 Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-tool-windows.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/intellij-tutorial.png b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-tutorial.png new file mode 100644 index 000000000..2b86dcf07 Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/intellij-tutorial.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/toolbox-install-ide.png b/doc/users-guide/modules/ROOT/images/technical-writing/toolbox-install-ide.png new file mode 100644 index 000000000..c8ef5657f Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/toolbox-install-ide.png differ diff --git a/doc/users-guide/modules/ROOT/images/technical-writing/toolbox-start-ide.png b/doc/users-guide/modules/ROOT/images/technical-writing/toolbox-start-ide.png new file mode 100644 index 000000000..f3ae8ffab Binary files /dev/null and b/doc/users-guide/modules/ROOT/images/technical-writing/toolbox-start-ide.png differ diff --git a/doc/users-guide/modules/ROOT/nav.adoc b/doc/users-guide/modules/ROOT/nav.adoc index 8bc7e6a99..58124ef4c 100644 --- a/doc/users-guide/modules/ROOT/nav.adoc +++ b/doc/users-guide/modules/ROOT/nav.adoc @@ -1,5 +1,11 @@ * xref:index.adoc[] * xref:quick-start.adoc[] +* xref:technical-writing/index.adoc[] +** xref:technical-writing/installing-intellij.adoc[] +** xref:technical-writing/starting-intellij-first-time.adoc[] +** xref:technical-writing/opening-the-first-project.adoc[] +** xref:technical-writing/editor-the-file-asciidoc-file.adoc[] +** xref:technical-writing/git-integration.adoc[] * xref:installation.adoc[] * xref:recommended-settings.adoc[] * xref:features.adoc[] diff --git a/doc/users-guide/modules/ROOT/pages/index.adoc b/doc/users-guide/modules/ROOT/pages/index.adoc index cc9e65f5c..53aeab9b7 100644 --- a/doc/users-guide/modules/ROOT/pages/index.adoc +++ b/doc/users-guide/modules/ROOT/pages/index.adoc @@ -41,10 +41,12 @@ It provides the writer with... == Where to go from here -To continue your journey, +To continue the journey with one of the following: -* visit the (short) xref:quick-start.adoc[] guide or (in depth) xref:installation.adoc[] guide, -* read about the xref:features.adoc[], or -* use the navigation on the left to learn about a specific topic you are interested in. +* Visit the +** (short) xref:quick-start.adoc[] guide or the +** (in depth) xref:technical-writing/index.adoc[] guide. +* Read about the xref:features.adoc[]. +* Use the navigation on the left to learn about a specific topic you are interested in. If you got questions, please raise them as a https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues[new GitHub issue]. diff --git a/doc/users-guide/modules/ROOT/pages/installation.adoc b/doc/users-guide/modules/ROOT/pages/installation.adoc index d6e1f322d..1d963b6c2 100644 --- a/doc/users-guide/modules/ROOT/pages/installation.adoc +++ b/doc/users-guide/modules/ROOT/pages/installation.adoc @@ -6,6 +6,11 @@ ifndef::env-site[] :imagesdir: ../images endif::[] +{description} + +For users already familiar with JetBrains IntelliJ, there's a xref:quick-start.adoc[] documentation. +For those new to IntelliJ, there is a xref:technical-writing/index.adoc[] with a step-by-step-guide installing IntelliJ for technical writing. + [#prerequisites] == Prerequisites diff --git a/doc/users-guide/modules/ROOT/pages/quick-start.adoc b/doc/users-guide/modules/ROOT/pages/quick-start.adoc index 12674dc41..9c6df3f1d 100644 --- a/doc/users-guide/modules/ROOT/pages/quick-start.adoc +++ b/doc/users-guide/modules/ROOT/pages/quick-start.adoc @@ -7,7 +7,8 @@ ifndef::env-site[] endif::[] {description} -Continue to section xref:installation.adoc[] for a more detailed guide. +Change to the page xref:installation.adoc[] for a more detailed guide, +or xref:technical-writing/index.adoc[] for a step-by-step-guide installing IntelliJ for technical writing. == Prerequisite diff --git a/doc/users-guide/modules/ROOT/pages/recommended-settings.adoc b/doc/users-guide/modules/ROOT/pages/recommended-settings.adoc index 66cb1cd5e..8e78ae6cd 100644 --- a/doc/users-guide/modules/ROOT/pages/recommended-settings.adoc +++ b/doc/users-guide/modules/ROOT/pages/recommended-settings.adoc @@ -11,23 +11,16 @@ endif::[] [#configuring-editor] == Configuring editor -. An AsciiDoc recommended practice is to have link:https://asciidoctor.org/docs/asciidoc-recommended-practices/[_one sentence per line_]. -This can lead to lines larger than the editor's width. -+ -Using soft wraps will make the content readable in the editor, as each line wraps at the width of the editor. -+ -Go to menu:File[Settings... > Editor > General > Soft Wraps] and enable soft wrap for the file extension you use for AsciiDoc files (usually *.adoc). -+ -image::enable-softwrap.png[Editor settings showing soft wrap] +include::partial$enable-soft-wrap.adoc[] == Configuring preview -. To get the best preview experience, switch the preview browser to _JavaFX WebView_ or _JCEF Browser_. +To get the best preview experience, switch the preview browser to _JavaFX WebView_ or _JCEF Browser_. See below how to <>. -+ + Go to menu menu:File[Settings... > Languages & Frameworks > AsciiDoc] to review or change this setting. If neither JavaFX of JCEF preview is not available, refer to xref:installation.adoc#prerequisites[Installation Prerequisites]. -+ + image::settings-asciidoc.png[AsciiDoc settings] If your preview is blurry, xref:faq/blurry-preview.adoc[follow these instructions to remedy this]. diff --git a/doc/users-guide/modules/ROOT/pages/technical-writing/editor-the-file-asciidoc-file.adoc b/doc/users-guide/modules/ROOT/pages/technical-writing/editor-the-file-asciidoc-file.adoc new file mode 100644 index 000000000..726e9b18a --- /dev/null +++ b/doc/users-guide/modules/ROOT/pages/technical-writing/editor-the-file-asciidoc-file.adoc @@ -0,0 +1,111 @@ += Editing an AsciiDoc file in IntelliJ +:navtitle: Editing an AsciiDoc file +:description: Adding a file to a project and editing AsciiDoc content in an existing project. + +{description} + +include::partial$technical-writing-series.adoc[] + +== Prerequisites + +This assumes that IntelliJ IDEA is open with an either empty project or a project with some existing content. +See xref:./opening-the-first-project.adoc[] on how to do this. + +== Adding an AsciiDoc file + +This creates a new file in an existing project that can later be edited. + +To add a file: + +. Right-click on a folder in the project view where the new file should appear. ++ +Assuming the user wants to create a file in the root folder empty project "`helloworld`", they would click on the bold text "`helloworld`" (see <> below). + +. Choose from the context menu the item menu:New[AsciiDoc File]. ++ +If the menu item for the AsciiDoc file is missing in the steps below, the AsciiDoc plugin wasn't installed in the prerequisite step. +Rectify this by following the steps in xref:installation.adoc#marketplace-via-settings[Installation via JetBrains Marketplace via the IDE's settings], then return here to continue. + +. Enter the new file name, and choose either an empty template or the Article template. + +. Press btn:[OK] + +When choosing the article template, and using a file name `README.adoc`, the result should look similar to the following screenshot. + +[[intellij-first-file]] +image::technical-writing/intellij-first-file.png[] + +== Configuring the Editor + +include::partial$enable-soft-wrap.adoc[] + +== IDE menus and tool windows + +This section describes the most important tool at the borders of the IDE's window as shown below. + +image::technical-writing/intellij-tool-windows.png[] + +. The project view is a tree view of all files in the project. +Clicking on "`Project`" hides and shows this view. +This is a functionality of all tool windows. + +. The structure view displays the structure of the current AsciiDoc file in the editor. +Clicking on "`Structure`" hides and shows this view. + +. In the editor window, the user can update the text as needed. + +. A toolbar at the top allows formatting of content and toggles the preview. +Hover with the mouse over the different icons until a description appears. + +. The preview shows the content from the editor. + +== Editor + +In the editor, the user can update the content. +It has syntax highlighting to improve legibility. +On the left of the editor window, small icon:minus[] icons allow the user to collapse sections and icon:plus[] icons to expand sections. +Line numbers help with the orientation. + +When the IDE suspects a problem, for example, a missing image or a broken reference, it underlines the text with a red line. +It uses similar highlighting for suspected spelling and grammar errors. + +The main things to know about the editor are: + +* When the user types the three letters kbd:[a]kbd:[d]kbd:[-], the editor suggests live templates for common AsciiDoc structures like lists, links and source code. +Continue typing to narrow down the list, use the up and down arrows to highlight an entry, and use kbd:[Enter] to select an entry. + +* When typing a file name as part of an image macro or a reference, kbd:[Ctrl+Space] shows a list of suggestions. +Press kbd:[Tab] to replace the text in editor for the current reference or press kbd:[Enter] to insert the text in the editor. + +* Using kbd:[Alt+Enter], the user can trigger context-specific features of the IDE, especially when there is an underlined text that indicate warnings and errors. +Those features range from creating a missing file to choose a correct word when there is a spelling or grammar mistake. + +* After placing the cursor on an include-macro or a reference and pressing kbd:[Ctrl+B], the IDE opens that file in a new editor tab. + +* To rename an attribute name, file name or reference, place the cursor on it and press kbd:[Shift+F6], and the IDE renames the reference in all places if the checkboxes are enabled in the dialog that pops up after the key was pressed. + +* To format the complete file or a selection of text, press kbd:[Ctrl+Alt+L]. +The default configuration removes unnecessary blanks and applies the one-sentence-per line rule. See xref:features/advanced/reformatting.adoc[] for details. + +To learn more about the editor's features, read the page xref:features/editor.adoc[]. + +To learn about the shortcuts in the IDE and the editor, read the page xref:features/keymap.adoc[]. + +== Preview + +Once the user places the cursor in the editor, the preview scrolls so that it shows this paragraph in the preview. + +The main things to know about the preview are: + +* Clicking on an external link opens them in a new window of the system's browser. + +* Clicking on an internal link opens the file in the editor. + +* Clicking on text content places the cursor in the editor in that paragraph. +If the content is from an included AsciiDoc file, the editor opens that file in a new editor tab. + +To learn more about the preview's features, read the page xref:features/preview.adoc[]. + +== Further reading + +Continue to xref:./git-integration.adoc[] for the next step of this series. diff --git a/doc/users-guide/modules/ROOT/pages/technical-writing/git-integration.adoc b/doc/users-guide/modules/ROOT/pages/technical-writing/git-integration.adoc new file mode 100644 index 000000000..40e8efe0a --- /dev/null +++ b/doc/users-guide/modules/ROOT/pages/technical-writing/git-integration.adoc @@ -0,0 +1,48 @@ += Collaborate with others using IntelliJ's Git integration +:navtitle: Collaborate using Git +:description: Setting up IntelliJ IDEA when starting it for the first time. + +{description} + +include::partial$technical-writing-series.adoc[] + +== Prerequisites + +This assumes that IntelliJ IDEA is already installed on the PC and is started and that the reader is familiar with editing content in IntelliJ. +See xref:./installing-intellij.adoc[] and xref:./editor-the-file-asciidoc-file.adoc[] on how to do this. + +In order for the Git functionality in IntelliJ to work, the user needs to install a Git client. + +== Accessing Git from the IntelliJ GUI + +This paragraph assumes that the user wants to use IntelliJ's integrated Git functionality. +To use the Git command line, choose the "`Terminal`" toolbox tab in IntelliJ to interact with the command line instead of following these steps. + +The following example assumes that: + +* The project is a checked-out remote repository. +* The local repository has a remote "`upstream`" with points to the main repository where people collaborate around a branch "`main`". +* The local repository has a remote "`origin`" with points to a clone of the main repository where the user wants to create a branch from where they want to create a pull request later. ++ The currently checked out branch in the local repository is "`main`" and points to the remote "`origin`". + +=== Overview of the controls and tool windows + +image::technical-writing/intellij-git.png[] + +. Git tool window, click on "`Git`" to show and hide the window. + +. With the "`Log`" tab active, it shows local and (if available) remote branches, plus the commits in the repository. + +. In the menu:Branch[] dropdown, select _HEAD_ to show only the commits of the current branch. + +. The "`Commit`" tool window shows all local changes that can then be committed. + +=== Learning more about Git functionality + +See https://www.jetbrains.com/help/idea/using-git-integration.html[the IntelliJ documentation] for details. +Use menu:Help[Learn IDE Features] and choose the next final section "`Git`" to start the tutorial covering Git. + +== Further reading + +This is the final page of the guide. +Return to the overview xref:./index.adoc[]. diff --git a/doc/users-guide/modules/ROOT/pages/technical-writing/index.adoc b/doc/users-guide/modules/ROOT/pages/technical-writing/index.adoc new file mode 100644 index 000000000..9e36635bf --- /dev/null +++ b/doc/users-guide/modules/ROOT/pages/technical-writing/index.adoc @@ -0,0 +1,46 @@ += Setup for technical writing +:description: This article guides users new to IntelliJ IDEA through the necessary steps to set up their environment for technical writing with AsciiDoc. + +{description} + +It describes best practices and shows an opinionated approach to make it simple for users new to IntelliJ. + +For users already familiar with JetBrains IntelliJ, there's a xref:quick-start.adoc[] documentation. +For advanced installation options, see the page xref:installation.adoc[]. + +== Why to use IntelliJ for technical writing + +The AsciiDoc plugin provides an as-you-type preview, syntax highlighting, auto-completion and content validation in one plugin. +The IntelliJ IDE offers a great integration with Git and also plugins for spell and grammar checking. + +To get a full overview of all features of the plugin, see xref:features.adoc[]. + +== Steps to set up a writer's environment + +Follow these steps to set up IntelliJ IDEA as the tool for technical writing. +Each page gives a brief overview to get started and links to other pages in this guide for additional information. + +. xref:./installing-intellij.adoc[Installing IntelliJ IDEA as the workplace for technical writing]. +. xref:./starting-intellij-first-time.adoc[Starting IntelliJ IDEA for the first time and installing the AsciiDoc plugin]. +. xref:./opening-the-first-project.adoc[Opening the first project in IntelliJ IDEA]. +. xref:./editor-the-file-asciidoc-file.adoc[Adding a file to a project and editing AsciiDoc content in an existing project.]. +. xref:./git-integration.adoc[Collaborate with others using IntelliJ IDEA's Git integration]. + +//// +. xref:./preparing-a-git-repository.adoc[Preparing a Git repository for AsciiDoc and IntelliJ to work with a team of technical writers]. +. xref:./recommended-plugins.adoc[Enhance a writer's productivity with plugins for IntelliJ]. +//// + +== Improving this guide + +Each of the pages in the guide has an "`Edit this page`" link in the upper right corner. +Use this to edit the content on GitHub. +As an alternative, all content to this guide is hosted in the https://github.com/asciidoctor/asciidoctor-intellij-plugin[Git repository of the AsciiDoc plugin] in the _doc_ folder, so it can be edited in an IDE like any other AsciiDoc content. + +If there are missing features, link:mailto:alexander.schwartz@gmx.net?subject=Feedback%20to%20IntelliJ%20Technical%20Setup[contact the maintainer via email] or https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues/new/choose[create an issue on GitHub]. + +== Further reading + +To get a full overview of all features of the plugin, see xref:features.adoc[]. + +To custom the plugin's settings, see xref:recommended-settings.adoc[] for recommended settings. diff --git a/doc/users-guide/modules/ROOT/pages/technical-writing/installing-intellij.adoc b/doc/users-guide/modules/ROOT/pages/technical-writing/installing-intellij.adoc new file mode 100644 index 000000000..0b8d2bd12 --- /dev/null +++ b/doc/users-guide/modules/ROOT/pages/technical-writing/installing-intellij.adoc @@ -0,0 +1,76 @@ += Installing IntelliJ for technical writing +:navtitle: Installing IntelliJ +:description: Follow these steps to install IntelliJ IDEA on a PC. + +{description} + +include::partial$technical-writing-series.adoc[] + +== Prerequisites + +This guide assumes that IntelliJ is about to be installed on either Windows, macOS or Linux. + +* *Windows:* 64-bit Windows 8 or newer +* *macOS:* macOS Mojave (10.14) or newer +* *Linux:* 64-bit x86, glibc 2.17 (Ubuntu 18.04 or newer). + +The following packages must be present: + +`+libfuse2 libxi6 libxrender1 libxtst6 mesa-utils libfontconfig libgtk-3-bin+` + +The installation requires an Internet connection to download about 700 MB. +See <> to install without an Internet connection. + +== What to install and why + +This guide will install JetBrains IntelliJ IDEA Community edition, which is free, doesn't need a subscription and is sufficient for technical writing with the AsciiDoc plugin. +See <> below for more details. + +To install it, this guide uses the JetBrains Toolbox as it allows a unified approach across all operating systems and an automated update procedure. +See <> below for alternatives. + +== Installing IntelliJ IDEA via the JetBrains Toolbox + +Follow these steps to install IntelliJ IDEA via the JetBrains Toolbox: + +. Download the Toolbox App from the https://www.jetbrains.com/toolbox-app/[Toolbox homepage]. +. On Windows and macOS: Start the installation. +On Linux: Extract the archive and start the executable. +. After the installation, the JetBrains Toolbox is started automatically. +Users can start it later like any other app from the list of installed applications. +. Choose the button btn:[Install] next to the IntelliJ IDEA Community Edition. +This will download and install the IDE. +The time to install depends on the speed of the internet connection to download approx. 600 MB. ++ +image::technical-writing/toolbox-install-ide.png[] +. After the installation is complete, users can start the installed IDE like any other locally installed application or directly by clicking the IDE in the toolbox. ++ +image::technical-writing/toolbox-start-ide.png[] + +*Next step:* Continue on page xref:./starting-intellij-first-time.adoc[]. + +[#other-ides-by-jetbrains] +== Other IDEs by JetBrains + +The company JetBrains maintains a portfolio of different IDEs with different target audiences. +Some of them are free and have "`Community`" in their name, others need a paid subscription. +Students at universities might get a free subscription, and there are trial periods to try out the paid subscriptions. + +* The IntelliJ IDEA Community and IntelliJ IDEA Ultimate editions target Java developers. + +* For Python developers, there is PyCharm Community, PyCharm Edu and PyCharm Ultimate. + +* For web developers, there is WebStorm. + +* For Android developers, there's Android Studio, which unfortunately requires some additional steps to enable the preview, see xref:features/preview/jcef-preview.adoc#choose-jdk[JCEF Preview documentation about Android Studio]. + +[#alternative-installation-options] +== Alternative installation options + +Users can also download IntelliJ IDEA from the JetBrains as an archive https://www.jetbrains.com/idea/download[from the download page]. +This is a good option to install the IDE on a PC which doesn't have an internet connection. + +Some Linux distributions contain pre-packaged versions of the IDE, but as those sometimes lack features or components that are required by the AsciiDoc plugin's preview. +Therefore, they are _not_ recommended. + +== Further reading + +Continue to xref:./starting-intellij-first-time.adoc[] for the next step of this series. diff --git a/doc/users-guide/modules/ROOT/pages/technical-writing/opening-the-first-project.adoc b/doc/users-guide/modules/ROOT/pages/technical-writing/opening-the-first-project.adoc new file mode 100644 index 000000000..398e55f54 --- /dev/null +++ b/doc/users-guide/modules/ROOT/pages/technical-writing/opening-the-first-project.adoc @@ -0,0 +1,43 @@ += Opening a project in IntelliJ IDEA +:navtitle: Opening a project +:description: Opening the first project in IntelliJ IDEA when starting it for the first time. + +{description} + +include::partial$technical-writing-series.adoc[] + +== Prerequisites + +This assumes that IntelliJ IDEA is already installed on the PC and is started. +See xref:./installing-intellij.adoc[] and xref:./starting-intellij-first-time.adoc[] on how to do this. + +== Opening a project + +A project is usually either a single folder on the local disk, or a remote Git repository. +While a project can xref:features/advanced/multimodule.adoc[consist of multiple local folders], this is an advanced case which is possible but not recommended for users new to IntelliJ. + +In this dialog, the user has the following options: + +New Project:: Choose a name and a local folder where to create the project. +For a technical writing project, choose the menu entry menu:Empty Project[] to avoid creating unnecessary build scripts. + +Open:: Choose a folder on the local disk to open it as a project. +Usually, this is the root folder of a previously checked-out Git repository. +If the project contains a lot of files, it might help to open only a sub-folder with the documentation. + +Get from VCS:: +Specify a URL with the remote repository and an empty local folder where to check out the files. + +Once the step is complete, IntelliJ opens the project in the IDE view. + +Assuming the user chose to create an empty project with the name "`helloworld`", the result will look similar to the following. + +image::technical-writing/intellij-empty-project.png[] + +To return to the start view, the user chooses the menu entry menu:File[Close Project]. +This view will then contain a list of previously opened projects. +The buttons for a new project, to open a folder and to get sources from VCS are in the upper row (smaller, and still with the same name as before). + +== Further reading + +Continue to xref:./editor-the-file-asciidoc-file.adoc[] for the next step of this series. diff --git a/doc/users-guide/modules/ROOT/pages/technical-writing/starting-intellij-first-time.adoc b/doc/users-guide/modules/ROOT/pages/technical-writing/starting-intellij-first-time.adoc new file mode 100644 index 000000000..78d21356b --- /dev/null +++ b/doc/users-guide/modules/ROOT/pages/technical-writing/starting-intellij-first-time.adoc @@ -0,0 +1,72 @@ += Starting IntelliJ for the first time +:navtitle: Starting IntelliJ +:description: Setting up IntelliJ IDEA when starting it for the first time. + +{description} + +include::partial$technical-writing-series.adoc[] + +== Prerequisites + +This assumes that IntelliJ IDEA is already installed on the PC. +See xref:./installing-intellij.adoc[] on how to do this. + +== First setup steps of the IDE + +When starting the IDE for the first time, this is the start screen: + +image::technical-writing/intellij-first-start.png[] + +This screen allows technical writers to + +* Opening a new or existing project + +* Customizing the IDE + +* Installing Plugins + +* Start a tutorial to learn an IntelliJ IDEA + +Users find a short introduction video in the online help for IntelliJ IDEA in chapter https://www.jetbrains.com/help/idea/run-for-the-first-time.html[Run IntelliJ IDEA for the first time]. + +Once the user opened their first project, IntelliJ IDEA will skip this screen and load the previous project. +Users can return to this screen by choosing the menu item menu:File[Close Project] until no project is open. +Then this screen appears again. + +Use the following sections to configure the IDE before opening the first project. + +=== Installing Plugins + +This dialog allows installing plugins from the JetBrains marketplace. +To install the AsciiDoc plugin, choose the tab menu:Marketplace[], type _AsciiDoc_ in the search field, and choose the AsciiDoc plugin. +Press the button btn:[Install] to install the plugin. + +image::technical-writing/intellij-install-plugin-asciidoc.png[] + +If a user wants to install, uninstall or disable plugins later, https://www.jetbrains.com/help/idea/managing-plugins.html[they can do this via the IDE's settings]. + +=== Optional: Customize the IDE + +The customize screen allows users to choose the color theme. +While dark mode ("`Darcula`") is the default, users can choose a light or high contrast mode. + +image::technical-writing/intellij-customize.png[] + +All future dialogs in this guide use the IntelliJ light theme. + +If a user wants to change this later, https://www.jetbrains.com/help/idea/user-interface-themes.html[this can be changed in the IDE's settings]. + +=== Optional: Start a tutorial to learn an IntelliJ IDEA + +The button btn:[Start Learning] starts a tutorial that explains the IDEs features. + +image::technical-writing/intellij-tutorial.png[] + +Most chapters of the tutorial use Java code to explain how the editor, auto-completion and refactoring works. +While the tutorial is about Java, most keyboard shortcuts and functionality will work similarly for AsciiDoc due to the installed AsciiDoc plugin. + +The last chapter that explains Git is based on a YAML file and could be helpful to technical writers not yet familiar with Git. + +== Further reading + +Continue to xref:./opening-the-first-project.adoc[] for the next step of this series. diff --git a/doc/users-guide/modules/ROOT/partials/enable-soft-wrap.adoc b/doc/users-guide/modules/ROOT/partials/enable-soft-wrap.adoc new file mode 100644 index 000000000..7626c6e4f --- /dev/null +++ b/doc/users-guide/modules/ROOT/partials/enable-soft-wrap.adoc @@ -0,0 +1,8 @@ +An AsciiDoc recommended practice is to have link:https://asciidoctor.org/docs/asciidoc-recommended-practices/[_one sentence per line_]. +This can lead to lines larger than the editor's width. + +Using soft wraps will make the content readable in the editor, as each line wraps at the width of the editor. + +Go to menu:File[Settings... > Editor > General > Soft Wraps] and enable soft wrap for the file extension you use for AsciiDoc files (usually *.adoc). + +image::enable-softwrap.png[Editor settings showing soft wrap] diff --git a/doc/users-guide/modules/ROOT/partials/technical-writing-series.adoc b/doc/users-guide/modules/ROOT/partials/technical-writing-series.adoc new file mode 100644 index 000000000..605691c64 --- /dev/null +++ b/doc/users-guide/modules/ROOT/partials/technical-writing-series.adoc @@ -0,0 +1,2 @@ +This is part of the step-by-step series to set up a technical writing environment with IntelliJ and the AsciiDoc plugin. +See the page xref:page$technical-writing/index.adoc[] for an overview of all steps.