Getting started

README.md

@@ -4,23 +4,20 @@ Official documentation and code examples for Vaadin.
 
 This repository does not generate the [vaadin.com/docs](https://vaadin.com/docs) or [hilla.dev/docs](https://hilla.dev/docs) websites. It only contains the content for them. The builds are done using [Vaadin Design System Publisher](https://vaadin.com/design-system-publisher).
 
-The `latest` branch is for Vaadin documentation and selected by default. Select the `hilla` branch if you wish to contribute to Hilla documentation.
-As an exception, any contributions to component documentation (including that related to Hilla) should be done to the `latest` branch.
-
 ## Contents
 
 Files not explicitly listed below are from the standard Vaadin project setup.
 
 ### `articles`
 
-A hierarchy of AsciiDoc (either `.asciidoc` or `.adoc`) files, documenting the use of all Vaadin features. The file path defines the resulting URL on the documentation site.
+A hierarchy of AsciiDoc files (`.adoc`), documenting the use of all Vaadin features. The file path defines the resulting URL on the documentation site.
 
 For example:
 
-- `articles/flow/intro/index.asciidoc` → `/intro/`
-- `articles/flow/forms/data-binding.asciidoc` → `/forms/data-binding/`
+- `articles/flow/index.adoc` → `/flow/`
+- `articles/flow/forms/data-binding.adoc` → `/flow/forms/data-binding/`
 
-See the [contribution guides](https://vaadin.com/docs/latest/contributing-docs/overview) to learn how to write documentation articles.
+See the [contribution guides](https://vaadin.com/docs/contributing/docs) to learn more.
 
 ### `frontend`
 
@@ -32,7 +29,7 @@ Flow/Java examples, which are included as rendered examples in the documentation
 
 ### `scripts`
 
-Project related scripts (tests, validation builds, preview deployment, etc).
+Project-related scripts (tests, validation builds, preview deployment, etc).
 
 ### `.github`
 

articles/components/grid/flow.adoc

@@ -34,7 +34,7 @@ grid.addColumn(Person::getYearOfBirth)
 layout.add(grid);
 ----
 
-`Grid` uses the [interfacename]`DataProvider` interface to communicate with the backend. The [methodname]`setItems()` method is a shorthand to create a [classname]`ListDataProvider`. For a large amount of data or other advanced use cases, you should probably use the [interfacename]`DataProvider` interface and lazy loading. See <<{articles}/binding-data/data-provider#,Data Providers>> for more information on this. See <<{articles}/flow/binding-data/data-provider#,Data Providers>> for more.
+`Grid` uses the [interfacename]`DataProvider` interface to communicate with the backend. The [methodname]`setItems()` method is a shorthand to create a [classname]`ListDataProvider`. For a large amount of data or other advanced use cases, you should probably use the [interfacename]`DataProvider` interface and lazy loading. See <</flow/binding-data/data-provider#,Data Providers>> for more information on this.
 
 include::{articles}/flow/binding-data/_items-identities.adoc[]
 
@@ -799,7 +799,7 @@ grid.addColumn(new ComponentRenderer<>(person -> {
 
 Incidentally, [methodname]`addComponentColumn()` is a shorthand for [methodname]`addColumn()` with a [classname]`ComponentRenderer`.
 
-Editing grid items requires refreshing the grid's [classname]`DataProvider`. The reasoning is the same as for <<Handling Events>> mentioned earlier. See <<{articles}/binding-data/data-provider#,Data Providers>> for more.
+Editing grid items requires refreshing the grid's [classname]`DataProvider`. The reasoning is the same as for <<Handling Events>> mentioned earlier. See <</flow/binding-data/data-provider#,Data Providers>> for more.
 
 
 == Enabling Expanding Rows
@@ -858,7 +858,7 @@ Depending on how the column was created, it may need additional configuration. I
 
 In-memory sorting is sorting that is automatically applied by the framework when using an in-memory data provider. Items are sorted using a `Comparator` that can either be created automatically by the column or has to be specified manually by the developer.
 
-Backend sorting is applied by providing a list of [classname]`QuerySortOrder` objects a custom [classname]`DataProvider` implemented by the developer. Sort order objects contain the property names that the developer must use for sorting items in their backend, such as a database. See <<{articles}/binding-data/data-provider#Sorting,Data Providers>> for more information on this.
+Backend sorting is applied by providing a list of [classname]`QuerySortOrder` objects a custom [classname]`DataProvider` implemented by the developer. Sort order objects contain the property names that the developer must use for sorting items in their backend, such as a database. See <</flow/binding-data/data-provider#Sorting,Data Providers>> for more information on this.
 
 With that in mind, you can determine which columns are automatically configured for in-memory or backend sorting:
 

articles/flow/create-ui/templates/polymer/index.adoc

@@ -19,7 +19,7 @@ ifdef::admonition[]
 endif::admonition[]
 Polymer support has been deprecated since Vaadin 18 (released in November 2020), in favor of faster and simpler <<{articles}/flow/create-ui/templates#,Lit templates>>. The built-in support for Polymer templates has been removed and is only available as a commercial add-on. However, a free conversion tool is available to assist in converting Polymer templates to Lit.
 
-Read more about setting up the commercial Polymer templates addon in the <<{articles}/flow/upgrading/#polymer-templates,Upgrade Guide>>.
+Read more about setting up the commercial Polymer templates addon in the <<{articles}/upgrading/#polymer-templates,Upgrade Guide>>.
 ifdef::admonition[]
 ====
 endif::admonition[]

articles/flow/guide/quick-start.adoc → articles/flow/quick-start.adoc

@@ -1,6 +1,6 @@
 ---
 title: Quick Start
-order: 10
+order: 2
 page-title: Vaadin Flow Quick Start
 description: How to build and deploy a modern web application completely in Java.
 ---
@@ -9,12 +9,12 @@ description: How to build and deploy a modern web application completely in Java
 = Vaadin Flow Quick Start
 :wizard-name: Vaadin Start
 
-Vaadin Flow helps you quickly to build web applications in pure Java -- without writing any HTML or JavaScript. This guide shows how to build a small, but fully functional ToDo application using Vaadin Flow.
+Vaadin Flow helps you build web applications in pure Java -- without writing any HTML or JavaScript. This guide shows how to build a small, but fully functional ToDo application using Vaadin Flow.
 
 
 == Requirements
 
-To start, you'll need JDK 17 or higher (e.g., https://adoptium.net/[Eclipse Temurin JDK]). Next, you'll need to download the quick start project. You can do so by clicking on the button here:
+To start, you'll need JDK 17 or higher (e.g., https://adoptium.net/[Eclipse Temurin JDK]). Next, you'll need to download the quick-start project. You can do so by clicking on the button here:
 
 ++++
 <p>
@@ -23,8 +23,7 @@ To start, you'll need JDK 17 or higher (e.g., https://adoptium.net/[Eclipse Temu
 </p>
 ++++
 
-Once you've done that, unpack the downloaded `ZIP` file into a local folder. Then <<./step-by-step/importing#, import the project into an IDE>>.
-
+Once you've done that, unpack the downloaded `ZIP` file into a local folder. Then <</getting-started/import#, import the project into an IDE>>.
 
 == Add Code
 
@@ -82,7 +81,7 @@ public class MainView extends VerticalLayout { // <2>
 
 What you've done so far may not seem like much, but it's enough to be able to run the application. To run it in your IDE, launch [filename]`Application.java`, located in the `src/main/java/org/vaadin/example` directory.
 
-Alternatively, you can run the project from the command-line by entering `./mvnw` on macOS or Linux systems, `mvnw` on Windows. Then, in your browser, open http://localhost:8080[`localhost:8080`, rel="nofollow"]. You should see the following:
+Alternatively, you can run the project from the command line by entering `./mvnw` on macOS or Linux systems, `mvnw` on Windows. Then, in your browser, open http://localhost:8080[`localhost:8080`, rel="nofollow"]. You should see the following:
 
 [.device]
 image::_images/completed-app.gif[Animation of adding a new ToDo item and checking it.]
@@ -95,7 +94,7 @@ The source code of this ToDo project is available at https://github.com/vaadin/f
 
 Now that you've seen how Vaadin Flow empowers you to build web applications -- quickly and in pure Java, without writing any HTML or JavaScript -- you're ready to learn more.
 
-Continue learning about Vaadin Flow by reading and watching the <<../tutorial/overview#, in-depth 2-hour course>> -- or create another application with custom views with Vaadin Start.
+Continue learning about Vaadin Flow by reading and watching the <<{articles}/flow/tutorial/overview#, in-depth 2-hour course>> -- or create another application with custom views with Vaadin Start.
 
 https://start.vaadin.com?preset=latest[Open {wizard-name}, role="button primary water"]
 

articles/flow/guide/step-by-step/importing/eclipse.adoc → articles/getting-started/import/eclipse.adoc

@@ -29,7 +29,7 @@ Finally, click [guibutton]*Finish*. Eclipse imports the project and starts downl
 
 After the import finishes, you are ready to explore the project. If you need to make changes to the configuration, see <</flow/configuration/properties#, Configuration>>.
 
-To run the application, proceed to <<../running/eclipse#, Running an Application in the Eclipse IDE>>.
+To run the application, proceed to <<../run/eclipse#, How to Run an Application in the Eclipse IDE>>.
 
 
 [discussion-id]`D11B4E49-0EF1-4FD5-B0B3-4B00D3778156`

articles/flow/guide/step-by-step/importing/index.adoc → articles/getting-started/import/index.adoc

@@ -1,15 +1,15 @@
 ---
-title: Importing to an IDE
-description: How to import a starter application into an IDE.
+title: Import to an IDE
+description: How to import a Vaadin starter application into an IDE.
 layout: tabbed-page
 tab-title: Overview
-order: 25
+order: 30
 ---
 
 
-= Importing to an IDE
+= Import a Vaadin Starter Project to an IDE
 
-Once you've downloaded and unpacked a starter application, you're ready to import it to your IDE. See <<{articles}/flow/guide/start#, Starting a Project>> for instructions for creating or downloading a starter project, or creating one from a Maven archetype.
+Once you've downloaded and unpacked a starter project, you're ready to import it to your IDE. See <</getting-started/project#, Start a Project>> for instructions for creating or downloading a starter project, or creating one from a Maven archetype.
 
 
 == Commonly Used IDEs

articles/getting-started/index.adoc

@@ -0,0 +1,6 @@
+---
+title: Getting Started
+description: Get started building applications on the Vaadin platform.
+order: 5
+section-nav: flat expanded
+---

articles/flow/guide/start/gradle.adoc → articles/getting-started/project/gradle.adoc

@@ -567,7 +567,7 @@ Whether to use React Router, add React core dependencies, React integration help
 
 When the list of dependencies causes the classpath to go over a set limit on Windows, the build automatically generates a JAR containing a manifest with the classpath. Sometimes, when running a Spring Boot application, the resource loader doesn't load the classpath packages correctly from the manifest. The failed annotation scanning makes the required `npm` packages unavailable.
 
-You can fix this in two ways: add the repository `mavenLocal()` to <<#build-file.repositories,build file repositories>>; or specify the `vaadin.allowed-packages` property, see <<../../integrations/spring/configuration#,Vaadin Spring Configuration>>.
+You can fix this in two ways: add the repository `mavenLocal()` to <<#build-file.repositories,build file repositories>>; or specify the `vaadin.allowed-packages` property, see <<{articles}/flow/integrations/spring/configuration#,Vaadin Spring Configuration>>.
 
 
 [discussion-id]`FA18F1BF-2C67-4CCF-85A2-C3E4D7AECFDB`

articles/flow/guide/start/index.adoc → articles/getting-started/project/index.adoc

@@ -3,7 +3,7 @@ title: Start a Project
 tab-title: Starter Projects
 description: How to build a new Vaadin project.
 layout: tabbed-page
-order: 20
+order: 10
 ---
 
 
@@ -16,11 +16,11 @@ The recommended way to start a new Vaadin project is to use *{wizard-name}*. Thi
 https://start.vaadin.com?preset=latest[Open {wizard-name}, role="button primary water"]
 
 
-== Vaadin Start Features
+== {wizard-name} Features
 
-The Vaadin Start on-line interface allows you to configure and download the core of a functional Vaadin project. At a minimum, you can then use that project as a starting point to create your own Vaadin application. Even more so, it allows you easily to do several fundamental things.
+The {wizard-name} online interface allows you to configure and download the core of a functional Vaadin project. At a minimum, you can then use that project as a starting point to create your own Vaadin application. Even more so, it allows you easily to do several fundamental things.
 
-First, Vaadin Start allows you to add several views to an application. You can select the initial content of each view from a list of more than fifteen templates. For example, you can include views based on the Master-Detail template, which can be used to manage an entity's data.
+First, {wizard-name} allows you to add several views to an application. You can select the initial content of each view from a list of more than fifteen templates. For example, you can include views based on the Master-Detail template, which can be used to manage an entity's data.
 
 image::_images/master-detail-template.png[Master-Detail Template, width=100%]
 
@@ -32,7 +32,7 @@ You can also set up security and configure access control. This can be configure
 
 image::_images/security-setup.png[Set up security and configure access control]
 
-Vaadin Start lets you easily change the look and feel of the application. Specifically, you can adjust the application's colors, typography, style, sizing, and spacing.
+{wizard-name} lets you easily change the look and feel of the application. Specifically, you can adjust the application's colors, typography, style, sizing, and spacing.
 
 image::_images/customize-theming.png[Customize Application Theme, width=50%]
 

articles/flow/guide/step-by-step/running/index.adoc → articles/getting-started/run/index.adoc

@@ -1,15 +1,15 @@
 ---
-title: Running an Application
-description: How to run an application.
+title: Run an Application
+description: How to run a Vaadin starter application.
 layout: tabbed-page
 tab-title: Overview
-order: 27
+order: 40
 ---
 
 
-= Running an Application
+= Run a Vaadin Starter Application
 
-After you have imported an application into your IDE, you're ready to run it. Applications created with <<{articles}/flow/guide/start#, Vaadin Start>> are Spring Boot applications, which you can run like ordinary Java applications. Non-Spring Boot applications can be run with Maven.
+After you have imported a starter application into your IDE, you're ready to run it. Applications created with <<{articles}/getting-started/project#, Vaadin Start>> are Spring Boot applications, which you can run like ordinary Java applications. Non-Spring Boot applications can be run with Maven.
 
 With a Spring Boot application like the ones created with *Vaadin Start*, you run the [classname]`Application` class in the project. This launches an embedded server to run the application.
 

articles/flow/guide/step-by-step/running/netbeans.adoc → articles/getting-started/run/netbeans.adoc

@@ -71,7 +71,7 @@ ifdef::web[]
 To learn more about:
 
 - The key concepts in Maven, see https://vaadin.com/learn/tutorials/learning-maven-concepts[Learning Maven concepts].
-- How to develop a Java web application without coding JavaScript or HTML, see the https://vaadin.com/learn/tutorials/vaadin-quick-start[Vaadin quick start tutorial].
+- How to develop a Java web application without coding JavaScript or HTML, see the <</flow/tutorial#,Vaadin Flow tutorial>>.
 endif::web[]
 
 

articles/hilla/start/faq.adoc → articles/hilla/faq.adoc

@@ -1,7 +1,7 @@
 ---
 title: FAQ
 description: "Frequently asked questions about the Hilla framework."
-order: 50
+order: 15
 ---
 :hilla-react:
 include::{root}/articles/hilla/lit/start/faq.adoc[tag=content]

articles/hilla/lit/reference/gradle.adoc

@@ -17,7 +17,7 @@ This particular page, though, describes how to compile, build, and run a Hilla a
 [NOTE]
 This tutorial doesn't describe Hilla application details. It seeks only to explore the Gradle-related parts for brevity. If you're interested in knowing more about the core concepts of Hilla applications, see
 ifdef::hilla-react[]
-<</hilla/start/quick#, Getting started with Hilla and React>>.
+<</hilla/quick-start#, Getting Started with Hilla and React>>.
 endif::[]
 ifdef::hilla-lit[]
 <</hilla/lit/start/quick#, Getting Started with Hilla and Lit>>.

articles/hilla/lit/start/faq.adoc

@@ -109,7 +109,7 @@ Neither Jakarta EE nor Quarkus support is on the roadmap. If you're interested i
 
 == Does Hilla Work with Multi-Module Projects?
 
-Yes. You can use standard Maven modules in your application, or even external dependencies, as there is no need for endpoints and entity classes to be in the same project as the Hilla application. See <<../reference/configuration#java-compiler-options,Configuration>> for details.
+Yes. You can use standard Maven modules in your application, or even external dependencies, as there is no need for endpoints and entity classes to be in the same project as the Hilla application. See <</hilla/reference/configuration#java-compiler-options,Configuration>> for details.
 
 
 == Does Kotlin, Scala, or Groovy Work with Hilla?

articles/hilla/lit/start/quick.adoc

@@ -7,8 +7,13 @@ order: 10
 :hilla-lit:
 // tag::content[]
 
+ifdef::hilla-react[]
+= Hilla Quick Start
+endif::[]
 
-= Quick Start
+ifdef::hilla-lit[]
+= Hilla & Lit Quick Start
+endif::[]
 
 This brief page can help you to get started doing this, quickly.
 
@@ -72,9 +77,9 @@ Another option is to download a starter project as a ZIP and extract it:
 
 ++++
 <p>
-<a 
+<a
 class="button primary water"
-href="https://start.vaadin.com/dl?preset=hilla&projectName=my-hilla-app" 
+href="https://start.vaadin.com/dl?preset=hilla&projectName=my-hilla-app"
 style="color:#FFFFFF"
  >Download</a>
 </p>
@@ -86,9 +91,9 @@ Another option is to download a starter project as a ZIP and extract it:
 
 ++++
 <p>
-<a 
+<a
 class="button primary water"
-href="https://start.vaadin.com/dl?preset=react&projectName=my-hilla-app" 
+href="https://start.vaadin.com/dl?preset=react&projectName=my-hilla-app"
 style="color:#FFFFFF"
  >Download</a>
 </p>

articles/hilla/start/basics/index.adoc → articles/hilla/tutorial/index.adoc

@@ -1,8 +1,8 @@
 ---
-title: Basics Tutorial
+title: Tutorial
 page-title: Spring Boot pass:[&] React Full-Stack Development Tutorial
 description: Hilla is a faster way to build full-stack React and Spring Boot applications. This tutorial shows you how to build a full-stack CRM application in 15 minutes.
-order: 30
+order: 12
 ---
 
 

articles/index.adoc

@@ -16,8 +16,8 @@ page-links:
 <h2>Develop Web Apps with Java</h2>
 <p class="lead">Build scalable user interfaces with Java, using the integrated frameworks, tooling, and components of Vaadin.
 <div class="buttons">
-xref:{articles}/flow/guide/quick-start#["Quick Start",role="button primary water"]
-xref:{articles}/flow/tutorial/overview#["Tutorial",role="button secondary water"]
+xref:/flow/quick-start#["Flow Quick Start",role="button primary water"]
+xref:/flow/tutorial/overview#["Tutorial",role="button secondary water"]
 </div>
 </p>
 </div>

articles/tools/mpr/introduction/5-adding-legacy-components.adoc

@@ -29,7 +29,7 @@ See the <<../configuration/adding-legacy-components#,Adding Legacy Components in
 
 == Adding New Views
 
-New views added to the application should follow Flow's routing system. In Flow, "Views" are called "RouteTargets" and are managed primarily by the `@Route` annotation. For details on the differences in navigation between Flow and previous Vaadin versions, see the <<{articles}/flow/upgrading#,Upgrading Guide>>.
+New views added to the application should follow Flow's routing system. In Flow, "Views" are called "RouteTargets" and are managed primarily by the `@Route` annotation. For details on the differences in navigation between Flow and previous Vaadin versions, see the <<{articles}/upgrading#,Upgrading Guide>>.
 
 For more information about Flow's navigation mechanism, see <<{articles}/flow/routing#,Routing and Navigation>>.
 
@@ -45,4 +45,4 @@ After your application is built and it's running with MPR, you should consider p
 <style>
 [class^=PageHeader-module--descriptionContainer] {display: none;}
 </style>
-++++
+++++