You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: DOCS/guidelines/editor-manual.qmd
+99-57Lines changed: 99 additions & 57 deletions
Original file line number
Diff line number
Diff line change
@@ -6,11 +6,8 @@ version: 0.6
6
6
description: "A comprehensive guide for creating technical documentation for the Copernicus
7
7
Land Monitoring Service using Quarto. It covers Markdown basics, document rendering,
8
8
and the review process, ensuring consistency and clarity in documentation."
9
-
date: "2025-06-04"
9
+
date: "2025-06-23"
10
10
template-version: 1.0
11
-
12
-
format:
13
-
html: default
14
11
---
15
12
16
13
<!--# maybe we should promote (or at least describe the option of unsing variables in yaml that can be reused in the document: e.g. product-name: "Example Product" --- # Welcome to {{ product-name }} Documentation. -->
@@ -19,13 +16,108 @@ format:
19
16
20
17
This manual guides users through creating technical documentation for the Copernicus Land Monitoring Service using [**Quarto**](https://quarto.org/). Quarto simplifies the process of writing professional documents in [**Markdown**](https://www.markdownguide.org/), and converting them into **HTML** and **PDF** for nice publishing. The manual covers basic Markdown writing, document rendering, as well a the review, and publication process of technical CLMS documents. It also describes the project folder structure, template usage, and common mistakes to avoid.
21
18
22
-
If you're responsible for setting up the documentation repository, follow the steps in [Adding Documentation to Your Project](#adding-documentation-to-your-project). Editors can skip this part and continue reading the manual to learn about editing and Markdown syntax.
23
-
24
19
::: callout-note
25
20
You don't need to be a programmer nor an expert to use Quarto. If you've ever written a document in Microsoft Word, you'll be able to use Quarto with a bit of practice.
26
21
:::
27
22
28
-
## Folder and File Structure
23
+
# Required Software
24
+
25
+
Before you can start writing documentation with Quarto, you’ll need to install a few tools. Most of them are quick to set up, and this chapter will guide you through what’s needed and why.
26
+
27
+
These tools help with writing, saving versions of your documents, and converting them into professional formats like HTML or PDF.
28
+
29
+
## Git
30
+
31
+
Git keeps track of your document changes over time. It also makes it easy to work with others without accidentally overwriting each other’s work. You don’t have to learn Git right away- but having it installed is important.
32
+
33
+
***Windows** users: [Download Git for Windows](https://git-scm.com/download/win).
34
+
***macOS** users: Git may already be installed. If not, you can install it using the Terminal.
35
+
***Linux** users: Use your package manager, e.g., `sudo apt install git`.
36
+
37
+
## RStudio
38
+
39
+
RStudio is a user-friendly editor where you’ll write and preview your documentation. It works great with Quarto and supports rendering documents into different formats.
40
+
41
+
* Download it from [rstudio.com](https://posit.co/download/rstudio-desktop/).
42
+
43
+
::: callout-note
44
+
Even though RStudio is made for programming in R, don’t worry—you’ll just use it as your writing tool for Quarto.
45
+
:::
46
+
47
+
## Quarto
48
+
49
+
Quarto is the main tool you'll be using to write and convert your documents into formats like HTML or PDF. It works together with RStudio and Pandoc.
50
+
51
+
Download it from [quarto.org](https://quarto.org/docs/get-started/)
52
+
53
+
After installation, Quarto works quietly in the background when you click "Render" in RStudio.
54
+
55
+
## Pandoc
56
+
57
+
Pandoc is the tool that turns your Markdown text into beautiful documents.
58
+
It often comes bundled with RStudio or Quarto. If you're not sure whether it's installed, don’t worry—Quarto will usually handle this for you behind the scenes.
59
+
60
+
## A Command Line Tool
61
+
62
+
Depending on your system, you’ll also need a basic command line tool to run a few simple commands:
63
+
64
+
***Windows**: Use **PowerShell**, which is already installed on most Windows computers.
65
+
***macOS or Linux**: Use the built-in **Terminal**, which gives you access to **bash** (the default command shell on most systems).
66
+
67
+
::: callout-tip
68
+
You’ll only need the command line for a few things, like starting a Quarto preview or checking if software is installed. We’ll walk you through these steps when the time comes.
69
+
:::
70
+
71
+
72
+
# Adding Documentation to Your Project
73
+
74
+
To integrate the documentation into your project, follow the steps below. Full instructions are available at: [https://github.com/eea/CLMS_documents_base](https://github.com/eea/CLMS_documents_base)
75
+
76
+
77
+
## Link the Base Repository
78
+
79
+
Add the base documentation repository as a remote:
Use the following command to pull in the documentation as a subtree:
88
+
89
+
```bash
90
+
git subtree add --prefix=DOCS clms-docs-base main --squash
91
+
```
92
+
93
+
After running this, your project will include a `DOCS/` directory containing all necessary documentation resources.
94
+
95
+
## Set Up Git Shortcuts
96
+
97
+
To simplify documentation management, run the appropriate setup script based on your operating system:
98
+
99
+
```bash
100
+
# On macOS or Linux:
101
+
./DOCS/_meta/scripts/linux/setup-docs-aliases.sh
102
+
103
+
# On Windows (PowerShell):
104
+
./DOCS/_meta/scripts/win/setup-docs-aliases.ps1
105
+
```
106
+
107
+
This will configure convenient Git aliases for working with the documentation.
108
+
109
+
## Available Git Aliases
110
+
111
+
Once the setup is complete, you'll have access to these useful Git commands:
112
+
113
+
-`git docs-update`: Syncs your local documentation with updates from the base repository.
114
+
-`git docs-publish`: Pushes your documentation changes to the repository.
115
+
-`git docs-preview`: Generates a local preview of your documentation.
116
+
117
+
These shortcuts make it easy to keep your documentation up-to-date, share changes, and review your work.
118
+
119
+
120
+
# Folder and File Structure
29
121
30
122
<!--# If this is for the doc part only, does it make sense to mention also the potential insert into an IT project, but can exist also on their own...(something like this, just mentioning it) -->
31
123
@@ -1144,56 +1236,6 @@ More issues will be added here as the system and workflow evolve. If you encount
1144
1236
1145
1237
# Document Review and Git Workflow
1146
1238
1147
-
## Adding Documentation to Your Project
1148
-
1149
-
To integrate the documentation into your project, follow the steps below. Full instructions are available at: [https://github.com/eea/CLMS_documents_base](https://github.com/eea/CLMS_documents_base)
1150
-
1151
-
1152
-
### Step 1: Link the Base Repository
1153
-
1154
-
Add the base documentation repository as a remote:
### Step 2: Add the `DOCS/` Folder to Your Project
1161
-
1162
-
Use the following command to pull in the documentation as a subtree:
1163
-
1164
-
```bash
1165
-
git subtree add --prefix=DOCS clms-docs-base main --squash
1166
-
```
1167
-
1168
-
After running this, your project will include a `DOCS/` directory containing all necessary documentation resources.
1169
-
1170
-
### Step 3: Set Up Git Shortcuts
1171
-
1172
-
To simplify documentation management, run the appropriate setup script based on your operating system:
1173
-
1174
-
```bash
1175
-
# On macOS or Linux:
1176
-
./DOCS/_meta/scripts/linux/setup-docs-aliases.sh
1177
-
1178
-
# On Windows (PowerShell):
1179
-
./DOCS/_meta/scripts/win/setup-docs-aliases.ps1
1180
-
```
1181
-
1182
-
This will configure convenient Git aliases for working with the documentation.
1183
-
1184
-
### Available Git Aliases
1185
-
1186
-
Once the setup is complete, you'll have access to these useful Git commands:
1187
-
1188
-
-`git docs-update`: Syncs your local documentation with updates from the base repository.
1189
-
-`git docs-publish`: Pushes your documentation changes to the repository.
1190
-
-`git docs-preview`: Generates a local preview of your documentation.
1191
-
1192
-
These shortcuts make it easy to keep your documentation up-to-date, share changes, and review your work.
1193
-
1194
-
1195
-
---
1196
-
1197
1239
## Pushing Changes to Git
1198
1240
1199
1241
Each project maintains documentation in its own `DOCS/` directory. When published to the Technical Library, your project's documents are available under a directory named after your project's Git repository name (`<PROJECT_NAME>`). These directories are managed as **git subtrees**, meaning their version history is isolated from the main repository for clarity and independence.
0 commit comments