Skip to content

shorter getting started #1245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 16, 2024
Merged

shorter getting started #1245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e19b1c1
shorter getting started
mbostock Apr 16, 2024
6962679
create intro; discussion link; ./path
mbostock Apr 16, 2024
f45ea2e
clarify HTML-in-Markdown
mbostock Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 28 additions & 118 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,87 +97,19 @@ If you prefer Yarn, run:

You can run the above command anywhere, but you may want to `cd` to your `~/Development` directory first (or wherever you do local development).

The first prompt asks where to create your new project. Enter `hello-framework` to create a directory named `hello-framework` within the current directory. Or just hit Enter, as this is the default. (You can create a project in a different directory by entering a relative path; on macOS or Linux, such paths start with `../` or `~/` or `/` _etc._)
This command will ask you a series of questions in order to initialize your new project. For this tutorial, you can simply hit Enter to accept the default values. When you’re done, you should see something like this:

<pre data-copy="none"><span class="muted">┌</span> <span class="invert"> observable create </span>
<span class="muted">│</span>
<span class="focus">◆</span> Where to create your project?
<span class="focus">│</span> hello-framework<span class="invert">&nbsp;</span>
<span class="focus">└</span></pre>

Next you’ll enter the project’s title. The title will appear in the sidebar as well as on all pages. You can hit Enter here to accept the default title, which is derived from the directory name you entered in the previous step.

<pre data-copy="none"><span class="muted">┌</span> <span class="invert"> observable create </span>
<span class="muted">│</span>
<span class="green">◇</span> Where to create your project?
<span class="muted">│</span> <span class="muted">hello-framework</span>
<span class="muted">│</span>
<span class="focus">◆</span> What to title your project?
<span class="focus">│</span> <span class="muted"><span class="invert">H</span>ello Framework</span>
<span class="focus">└</span></pre>

Next, you’ll be asked whether you want sample files in your new project. These files demonstrate common techniques and are handy for learning — you can edit the code and see what happens. You’ll want them now for this tutorial, but in the future you can omit them if you’d prefer a minimal starter project.

<pre data-copy="none"><span class="muted">┌</span> <span class="invert"> observable create </span>
<span class="muted">│</span>
<span class="green">◇</span> Where to create your project?
<span class="muted">│</span> <span class="muted">hello-framework</span>
<span class="muted">│</span>
<span class="green">◇</span> What to title your project?
<span class="muted">│</span> <span class="muted">Hello Framework</span>
<span class="muted">│</span>
<span class="focus">◆</span> Include sample files to help you get started?
<span class="focus">│</span> <span class="green">●</span> Yes, include sample files <span class="muted">(recommended)</span>
<span class="focus">│</span> <span class="muted">○ No, create an empty project</span>
<span class="focus">└</span></pre>

If you use npm or Yarn as your preferred package manager, declare your allegiance now. The package manager you used to launch `observable create` will be selected by default, so you can just hit Enter again to continue. If you prefer a different package manager (say pnpm), choose `No`; you can install dependencies after the project is created.

<pre data-copy="none"><span class="muted">┌</span> <span class="invert"> observable create </span>
<span class="muted">│</span>
<span class="green">◇</span> Where to create your project?
<span class="muted">│</span> <span class="muted">hello-framework</span>
<span class="muted">│</span>
<span class="green">◇</span> What to title your project?
<span class="muted">│</span> <span class="muted">Hello Framework</span>
<span class="muted">│</span>
<span class="green">◇</span> Include sample files to help you get started?
<span class="muted">│</span> <span class="muted">Yes, include sample files</span>
<span class="muted">│</span>
<span class="focus">◆</span> Install dependencies?
<span class="focus">│</span> <span class="muted">○ Yes, via npm</span>
<span class="focus">│</span> <span class="green">●</span> Yes, via yarn <span class="muted">(recommended)</span>
<span class="focus">│</span> <span class="muted">○ No</span>
<span class="focus">└</span></pre>

If you’ll continue developing your project after you finish this tutorial and want source control, answer `Yes` to initialize a git repository. Or say `No` — you can always do it later by running `git init`.

<pre data-copy="none"><span class="muted">┌</span> <span class="invert"> observable create </span>
<span class="muted">│</span>
<span class="green">◇</span> Where to create your project?
<span class="muted">│</span> <span class="muted">hello-framework</span>
<span class="muted">│</span>
<span class="green">◇</span> What to title your project?
<span class="muted">│</span> <span class="muted">Hello Framework</span>
<span class="muted">│</span>
<span class="green">◇</span> Include sample files to help you get started?
<span class="muted">│</span> <span class="muted">Yes, include sample files</span>
<span class="muted">│</span>
<span class="green">◇</span> Install dependencies?
<span class="muted">│</span> <span class="muted">Yes, via yarn</span>
<span class="green">◆</span> Welcome to Observable Framework! 👋 This command will help you create a new
<span class="muted">│</span> project. When prompted, you can press Enter to accept the default value.
<span class="muted">│</span>
<span class="focus">◆</span> Initialize a git repository?
<span class="focus">│</span> <span class="green">●</span> Yes <span class="muted">/ ○ No</span>
<span class="focus">└</span></pre>

And that’s it! After some downloading, copying, and installing, your new project is ready to go. 🎉

<pre data-copy="none"><span class="muted">┌</span> <span class="invert"> observable create </span>
<span class="muted">│</span> Want help? <u>https://observablehq.com/framework/getting-started</u>
<span class="muted">│</span>
<span class="green">◇</span> Where to create your project?
<span class="muted">│</span> <span class="muted">hello-framework</span>
<span class="green">◇</span> Where should we create your project?
<span class="muted">│</span> <span class="muted">./hello-framework</span>
<span class="muted">│</span>
<span class="green">◇</span> What to title your project?
<span class="green">◇</span> What should we title your project?
<span class="muted">│</span> <span class="muted">Hello Framework</span>
<span class="muted">│</span>
<span class="green">◇</span> Include sample files to help you get started?
Expand All @@ -198,7 +130,9 @@ And that’s it! After some downloading, copying, and installing, your new proje
<span class="muted">│</span> <span class="muted">│</span>
<span class="muted">├────────────────────────╯</span>
<span class="muted">│</span>
<span class="muted">└</span> Problems? <u><a href="https://observablehq.com/framework/getting-started" style="color: inherit;">https://observablehq.com/framework/getting-started</a></u></pre>
<span class="muted">└</span> Problems? <u><a href="https://github.com/observablehq/framework/discussions" style="color: inherit;">https://github.com/observablehq/framework/discussions</a></u></pre>

And that’s it! Your new project is ready to go. 🎉

## 2. Develop

Expand Down Expand Up @@ -533,74 +467,50 @@ _Ta-da!_ 🎉 Perhaps not the most exciting dashboard yet, but it has potential!

## 3. Publish

When you’re ready to share your project — whether privately with specific people you want to invite, or publicly with the world — you can quickly deploy it to [Observable](https://observablehq.com) using the `deploy` command:
When you’re ready to share your project — either privately or publicly — you can quickly deploy it to [Observable](https://observablehq.com) using the `deploy` command:

<pre data-copy>npm run deploy</pre>

Or with Yarn:

<pre data-copy>yarn deploy</pre>

<div class="note">If you don’t have an Observable account yet, the first time you deploy you’ll be prompted to create one. Observable is free for individuals and small teams, and we offer paid tiers for larger teams.</div>

If this is your first time deploying to Observable, you’ll be prompted to create a new project. This determines where you project lives on Observable.

<div class="tip">Your deploy configuration is saved to <code>docs<span class="wbr">/</span>.observablehq<span class="wbr">/</span>deploy.json</code>. When collaborating on a project, you should commit this file to git so your collaborators don’t have to separately configure deploy.</div>

<pre data-copy="none">
<span class="muted">┌</span> <span class="invert"> observable deploy </span>
<span class="muted">│</span>
<span class="blue">●</span> To configure deploy, we need to ask you a few questions.
<span class="muted">│</span>
<span class="green">◇</span> Deploying to the <b>ACME Inc. (@acme)</b> workspace.
<span class="muted">│</span>
<span class="blue">◆</span> No projects found. Do you want to create a new project?
<span class="blue">│</span> <span class="green">●</span> Yes, continue / <span class="muted">○ No, cancel</span>
<span class="blue">└</span>
</pre>

<div class="note">If you have multiple workspaces on Observable, you’ll be prompted to chose a workspace before creating a project. And if you’ve previously deployed projects to your chosen workspace, you can chose to deploy to an existing project, overwriting its contents.</div>
<div class="note">If you don’t have an Observable account yet, you will be prompted to sign up. Observable is free for individuals and small teams, and we offer paid tiers for larger teams.</div>

When creating a new project, you need to specify a <i>slug</i> which — together with your workspace username — determines the URL of your project. The slug is a short identifier consisting of lowercase letters, numbers, and hyphens. By default, Framework will suggest a slug based on your project’s title. You can change the slug later, and Observable will automatically redirect to the latest URL.
This command will ask you a few questions to configure your deploy, including which Observable workspace to use and whether the project should be public or private. You can also enter an optional message to associate with the deploy, but for now feel free to leave this blank by hitting Enter.

<pre data-copy="none">
<span class="muted">┌</span> <span class="invert"> observable deploy </span>
<span class="muted">│</span>
<span class="blue">●</span> To configure deploy, we need to ask you a few questions.
<span class="muted">│</span>
<span class="green">◇</span> Which Observable workspace do you want to use?
<span class="muted">│ ACME Inc. (@acme)</span>
<span class="muted">│ ACME Inc. (@example)</span>
<span class="muted">│</span>
<span class="green">◇</span> Which project do you want to use?
<span class="muted">│ Create a new project</span>
<span class="muted">│</span>
<span class="blue">◆</span> What slug do you want to use?
<span class="blue">│</span> <span class="muted"><span class="invert">h</span>ello-framework</span>
<span class="blue">└</span>
</pre>

Lastly, you can enter an optional deploy message. Deploy messages are shown on Observable and help you keep track of deploy history. For now, you can just leave this blank by hitting Enter.

<pre data-copy="none">
<span class="muted">┌</span> <span class="invert"> observable deploy </span>
<span class="green">◇</span> What slug do you want to use?
<span class="muted">│ hello-framework</span>
<span class="muted">│</span>
<span class="blue">●</span> To configure deploy, we need to ask you a few questions.
<span class="green">◇</span> Who is allowed to access your project?
<span class="muted">│ Private</span>
<span class="muted">│</span>
<span class="green">◇</span> Which Observable workspace do you want to use?
<span class="muted">│ ACME Inc. (@acme)</span>
<span class="green">◇</span> What changed in this deploy?
<span class="muted">│</span> <span class="muted">Enter a deploy message (optional)</span>
<span class="muted">│</span>
<span class="green">◇</span> Which project do you want to use?
<span class="muted">│ Create a new project</span>
<span class="green">◇</span> 18 uploaded
<span class="muted">│</span>
<span class="green">◇</span> What slug do you want to use?
<span class="muted">│ hello-framework</span>
<span class="green">◇</span> Deploy complete
<span class="muted">│</span>
<span class="blue">◆</span> What changed in this deploy?
<span class="blue">│</span> <span class="muted"><span class="invert">E</span>nter a deploy message (optional)</span>
<span class="blue">└</span>
<span class="muted">└</span> <span class="muted">Deployed project now visible at <u>https://example.observablehq.cloud/hello-framework/</u></span>
</pre>

When deploy completes, Framework will show your project’s URL on observablehq.cloud. From there you can invite people to your private workspace to see your project, or make your project public so anyone can see it.
When deploy completes, Framework will show your project’s URL on observablehq.cloud.

<div class="tip">Your deploy configuration is saved to <code>docs<span class="wbr">/</span>.observablehq<span class="wbr">/</span>deploy.json</code>. When collaborating on a project, you should commit this file to git so your collaborators don’t have to separately configure deploy.</div>

From there you can invite people to your private workspace to see your project, or make your project public so anyone can see it.

### Self hosting

Expand Down
18 changes: 17 additions & 1 deletion docs/markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ The `note`, `tip`, `warning`, and `caution` classes can be used to insert labele
<div class="caution">This is a caution.</div>
```

Markdown is not supported within HTML, so if you want rich formatting or links within a note, you must write it as HTML. (In the future, we may add support for notes within Markdown.)
Per [CommonMark](https://spec.commonmark.org/0.30/#html-blocks), the contents of an HTML block (such as a `<div class="note">`) are interpreted as HTML. For rich formatting or links within a note, use HTML.

<div class="tip">
<p>This is a <i>styled</i> tip using <small>HTML</small>.</p>
Expand All @@ -247,6 +247,22 @@ Markdown is not supported within HTML, so if you want rich formatting or links w
</div>
```

Alternatively, use blank lines to separate the contents of the note from the note container, and then the contents will be interpreted as Markdown.

<div class="tip">

This is a *styled* tip using **Markdown**.

</div>

```md run=false
<div class="tip">

This is a *styled* tip using **Markdown**.

</div>
```

You can override the note’s label using the `label` attribute.

<div class="warning" label="⚠️ Danger ⚠️">No lifeguard on duty. Swim at your own risk!</div>
Expand Down
2 changes: 1 addition & 1 deletion src/convert.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ export async function convert(
effects: ConvertEffects = defaultEffects
): Promise<void> {
const {clack} = effects;
clack.intro(`${inverse(" observable convert ")}`);
clack.intro(`${inverse(" observable convert ")} ${faint(`v${process.env.npm_package_version}`)}`);
let n = 0;
for (const input of inputs) {
let start = Date.now();
Expand Down
14 changes: 10 additions & 4 deletions src/create.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,20 +39,26 @@ const defaultEffects: CreateEffects = {
export async function create(effects: CreateEffects = defaultEffects): Promise<void> {
const {clack} = effects;
clack.intro(`${inverse(" observable create ")} ${faint(`v${process.env.npm_package_version}`)}`);
const defaultRootPath = "hello-framework";
const defaultRootPath = `.${op.sep}hello-framework`;
const defaultRootPathError = validateRootPath(defaultRootPath);
clack.log.success(
wrapAnsi(
"Welcome to Observable Framework! 👋 This command will help you create a new project. When prompted, you can press Enter to accept the default value.",
Math.min(80, effects.outputColumns)
) + `\n\nWant help? ${link("https://observablehq.com/framework/getting-started")}`
);
await clack.group(
{
rootPath: () =>
clack.text({
message: "Where to create your project?",
message: "Where should we create your project?",
placeholder: defaultRootPath,
defaultValue: defaultRootPathError ? undefined : defaultRootPath,
validate: (input) => validateRootPath(input, defaultRootPathError)
}),
projectTitle: ({results: {rootPath}}) =>
clack.text({
message: "What to title your project?",
message: "What should we title your project?",
placeholder: inferTitle(rootPath!),
defaultValue: inferTitle(rootPath!)
}),
Expand Down Expand Up @@ -131,7 +137,7 @@ export async function create(effects: CreateEffects = defaultEffects): Promise<v
if (spinning) s.stop("Installed! 🎉");
const instructions = [`cd ${rootPath}`, ...(packageManager ? [] : [installCommand]), `${runCommand} dev`];
clack.note(instructions.map((line) => reset(cyan(line))).join("\n"), "Next steps…");
clack.outro(`Problems? ${link("https://observablehq.com/framework/getting-started")}`);
clack.outro(`Problems? ${link("https://github.com/observablehq/framework/discussions")}`);
}
},
{
Expand Down
4 changes: 2 additions & 2 deletions src/deploy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ import {defaultEffects as defaultConfigEffects, getDeployConfig, setDeployConfig
import {slugify} from "./slugify.js";
import {Telemetry} from "./telemetry.js";
import type {TtyEffects} from "./tty.js";
import {bold, defaultEffects as defaultTtyEffects, inverse, link, underline, yellow} from "./tty.js";
import {bold, defaultEffects as defaultTtyEffects, faint, inverse, link, underline, yellow} from "./tty.js";

const DEPLOY_POLL_MAX_MS = 1000 * 60 * 5;
const DEPLOY_POLL_INTERVAL_MS = 1000 * 5;
Expand Down Expand Up @@ -79,7 +79,7 @@ export async function deploy(
): Promise<void> {
const {clack} = effects;
Telemetry.record({event: "deploy", step: "start", force});
clack.intro(inverse(" observable deploy "));
clack.intro(`${inverse(" observable deploy ")} ${faint(`v${process.env.npm_package_version}`)}`);

let apiKey = await effects.getObservableApiKey(effects);
const apiClient = new ObservableApiClient(apiKey ? {apiKey, clack} : {clack});
Expand Down
4 changes: 2 additions & 2 deletions src/observableApiAuth.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import {
} from "./observableApiConfig.js";
import {Telemetry} from "./telemetry.js";
import type {TtyEffects} from "./tty.js";
import {bold, defaultEffects as defaultTtyEffects, inverse, link, yellow} from "./tty.js";
import {bold, defaultEffects as defaultTtyEffects, faint, inverse, link, yellow} from "./tty.js";

const OBSERVABLE_UI_ORIGIN = getObservableUiOrigin();

Expand All @@ -39,7 +39,7 @@ export const defaultEffects: AuthEffects = {
export async function login(effects: AuthEffects = defaultEffects, overrides = {}) {
const {clack} = effects;
Telemetry.record({event: "login", step: "start"});
clack.intro(inverse(" observable login "));
clack.intro(`${inverse(" observable login ")} ${faint(`v${process.env.npm_package_version}`)}`);

const {currentUser} = await loginInner(effects, overrides);

Expand Down