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/getting-started.md
+72-33Lines changed: 72 additions & 33 deletions
Original file line number
Diff line number
Diff line change
@@ -13,9 +13,15 @@
13
13
14
14
# Getting started
15
15
16
-
Welcome! This tutorial will guide your first steps with Observable Framework. (We’ll refer to it as “Framework” for short.) If you follow this tutorial to the end, you’ll have a live dashboard ready to share. 🚀
16
+
Welcome! This tutorial will guide your first steps with Observable Framework. (We call it “Framework” for short.) Framework is a new way of building data apps that combines the power of JavaScript for interactive graphics on the front-end with any language you want on the back-end for data preparation and analysis.
17
17
18
-
Before we begin, let’s review the development workflow, end-to-end. Framework is a **local development server**, a **static site generator**, and a **command-line interface** to Observable, all rolled into one!
18
+
In this tutorial, you’ll create a live dashboard of your local weather. 🌦️ But before we begin, let’s first review the end-to-end development workflow. Framework is three things in one:
19
+
20
+
- a **local development server** that you use to preview your project locally during development, with instant updates as you save changes,
21
+
- a **static site generator** that compiles your Markdown, JavaScript, and other sources and static assets — alongside data snapshots generated dynamically by loaders — into a static site that you can host anywhere, and
22
+
- a **command-line interface** to Observable so that you can quickly and securely share your site with your team (or the world, or whoever).
23
+
24
+
We’ll touch on each of these parts in this tutorial.
19
25
20
26
```js
21
27
constdigraph= dot`digraph {
@@ -45,56 +51,81 @@ const digraph = dot`digraph {
45
51
<figcaption>An overview of the development workflow.</figcaption>
46
52
</figure>
47
53
48
-
You’ll first [**create**](#2.-create) a new project, setting up your local development environment.
54
+
You’ll first setup your local development environment by [**creating**](#2.-create) a new project.
49
55
50
-
Next you’ll [**develop**](#3.-develop). This is an iterative process where you save changes to Markdown and other source files in your preferred editor, and then preview the result running locally in your browser.
56
+
Next you’ll [**develop**](#3.-develop). This is an iterative process where you save changes to source files in your editor, and then preview the result running locally in your browser.
51
57
52
-
When you’re ready to share with your team (or the world), it’s time to [**publish**](#4.-publish). You can either build a static site for self-hosting or hosting on a third-party such as GitHub or Netlify, or you can deploy directly to Observable.
58
+
When you’re ready to share your work, it’s time to [**publish**](#4.-publish). You can either build a static site for self-hosting or you can deploy directly to Observable.
53
59
54
60
Lastly, you can invite people to [**view**](#5.-view) your project!
55
61
62
+
Of course, you can continue to develop your project after you publish, and then republish to make these changes live. And you can setup continuous deployment so that your site re-builds whenever you push a commit or on a fixed schedule. We’ll cover these [next steps](#next-steps) briefly below.
63
+
64
+
Here we go… 🚀
65
+
56
66
## 1. Create
57
67
58
-
<divclass="tip">Observable Framework is a <ahref="https://nodejs.org/">Node.js</a> application. You must have <ahref="https://nodejs.org/en/download">Node.js 20.6 or later</a> installed before you can install Framework.</div>
68
+
Observable Framework includes a helper script, `observable create`, for creating new projects. After a few quick prompts — where to create the project, your preferred package manager, *etc.* — it will create a fresh project from a template.
59
69
60
-
To create a new project, you can use `npm`:
70
+
<divclass="tip">Observable Framework is a <ahref="https://nodejs.org/">Node.js</a> application. You must have <ahref="https://nodejs.org/en/download">Node.js 20.6 or later</a> installed before you can install Framework. Observable Framework is a command-line interface (CLI) and runs in the terminal.</div>
71
+
72
+
To create a new project with `npm`, run:
61
73
62
74
```sh
63
75
npm init @observablehq
64
76
```
65
77
66
-
Or if you prefer `yarn`:
78
+
Or to create a new project with `yarn`, run:
67
79
68
80
```sh
69
81
yarn create @observablehq
70
82
```
71
83
72
-
This runs `observable create`, our helper script for creating new projects. You will be asked several questions, starting with where to create the new project.
84
+
You can run the above command anywhere, but maybe `cd` to your `~/Development` directory first (or wherever you do local development).
85
+
86
+
First you’ll need to specify where to create the new project. For this tutorial, we want to create a folder called `local-weather` within the current directory, so enter `./local-weather` at the prompt. (This path is equivalent to `local-weather`; we’re just showing that you can use `../` or `/` or `~/` to create a project anywhere.)
Next you’ll need to enter a project title. The title appears in the sidebar as well as on pages. (A memorable name will make your project easier to find in your browser history, for one.) You can just hit Enter here to accept the default title derived from the directory you entered in the previous step.
We’ll use the name `./hello-framework`for our project folder.
105
+
Next, you can decide whether to include sample files in your new project. These sample files will demonstrate a few tricks, and are handy for learning by tinkering, since you can just edit the code and see what happens. But if you’d prefer a more minimal starter project, you can chose to omit them. We recommend you include them (again, learning), but they’re not needed for this tutorial.
<spanclass="focus">◆</span> Include sample files to help you get started?
88
116
<spanclass="focus">│</span> <spanclass="green">●</span> Yes, include sample files <spanclass="muted">(recommended)</span>
89
117
<spanclass="focus">│</span> <spanclass="muted">○ No, create an empty project</span>
90
118
<spanclass="focus">└</span></pre>
91
119
92
-
…
120
+
If you use `npm` or `yarn` as your preferred package manager, you should now declare your allegiance. If you’re not sure, chose `npm`. If you prefer a different package manager (say `pnpm`), choose `No`, and then you can install dependencies yourself after the project is created.
If you choose a package manager here, we’ll automatically install dependencies when the project is created. If you want to use something besides `npm` or `yarn`, we’ll leave it to you.
109
-
110
-
…
139
+
If you’re going to develop this dashboard further, you’ll likely want source control to track changes and collaborate. Answer `Yes` to initialize a git repository for your no project. This is optional, and you can always do it later by running `git init`.
After answering a few questions, this command will create a new project folder in the current working directory.
187
+
<divclass="tip">If you have any issues creating a new project, please visit the <ahref="https://talk.observablehq.com">Observable Forum</a> or our <ahref="https://github.com/observablehq/cli/discussions">GitHub discussions</a> to ask for help.</div>
153
188
154
-
```sh
155
-
cd hello-world
156
-
```
189
+
## 3. Develop
190
+
191
+
If you haven’t already, `cd` into your new project folder.
157
192
158
193
```sh
159
-
yarn
194
+
cd local-weather
160
195
```
161
196
162
-
## 3. Develop
197
+
In preview mode, Framework generates HTML pages on-demand as you view a local version of your site in the browser. As you edit files, changes will be instantly reflected in the browser.
163
198
164
-
After you’ve initialized your project, you can start developing locally. In preview mode, Framework generates HTML pages on-demand as you view a local version of your site in the browser. As you edit files, changes will be instantly reflected in the browser.
199
+
To start the preview server using `npm`:
200
+
201
+
```sh
202
+
npm run dev
203
+
```
165
204
166
-
To start the preview server:
205
+
Or to start the preview server using `yarn`:
167
206
168
207
```sh
169
208
yarn dev
@@ -210,11 +249,11 @@ You can schedule builds and deploy your project automatically on commit, or on a
210
249
You can install Framework as a dependency on an existing project if you don’t want to create a new project using our default template as described above.
211
250
212
251
```sh
213
-
npm install @observablehq/framework
252
+
npm install @observablehq/cli
214
253
```
215
254
216
255
```sh
217
-
yarn add @observablehq/framework
256
+
yarn add @observablehq/cli
218
257
```
219
258
220
259
You can also install Framework globally so that the `observable` command is available across projects, but we don’t recommend this approach. By installing Framework into each project, everyone you work with will use the same version.
Copy file name to clipboardExpand all lines: docs/index.md
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -26,9 +26,9 @@ toc: false
26
26
27
27
</style>
28
28
29
-
**Observable Framework** is an [open-source](https://github.com/observablehq/cli) static site generator for data apps, dashboards, reports, and more. Framework includes a preview server for local development, and a command-line interface for automating build & deploy.
29
+
**Observable Framework** is an [open-source](https://github.com/observablehq/cli) static site generator for data apps, dashboards, reports, and more. Framework includes a preview server for local development, and a command-line interface for automating builds & deploys.
30
30
31
-
You write simple [Markdown](./markdown) pages — with interactive charts and inputs in [reactive JavaScript](./javascript), and data snapshots generated by [loaders](./loaders) in any programming language (SQL, Python, R, and more) — and Framework compiles it into a static site with instant page loads for a great user experience. Since everything is just files, you can use your preferred editor and source control, write unit tests, share code with other apps, integrate with CI/CD, and host projects anywhere.
31
+
You write simple [Markdown](./markdown) pages — with interactive charts and inputs in [reactive JavaScript](./javascript), and with data snapshots generated by [loaders](./loaders) in _any_ programming language (SQL, Python, R, and more) — and Framework compiles it into a static site with instant page loads for a great user experience. Since everything is just files, you can use your preferred editor and source control, write unit tests, share code with other apps, integrate with CI/CD, and host projects anywhere.
32
32
33
33
Framework includes thoughtfully-designed [themes and components](./components) to help you build displays of data that look great on any device. And you can quickly craft custom components using open-source libraries such as [Observable Plot](./lib/plot), [D3.js](./lib/d3), [Vega-Lite](./lib/vega-lite), [Graphviz](./lib/graphviz), [Mermaid](./lib/mermaid), [Leaflet](./lib/leaflet), [KaTeX](./lib/tex), and myriad more. (And for working with data, don’t forget about [Arquero](./lib/arquero), [DuckDB](./lib/duckdb), and [SQLite](./lib/sqlite), too.)
0 commit comments