diff --git a/docs/getting-started.md b/docs/getting-started.md
index 3b0fca6fb..99ebfdba2 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -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:
┌ observable create
│
-◆ Where to create your project?
-│ hello-framework
-└
-
-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.
-
-┌ observable create
-│
-◇ Where to create your project?
-│ hello-framework
-│
-◆ What to title your project?
-│ Hello Framework
-└
-
-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.
-
-┌ observable create
-│
-◇ Where to create your project?
-│ hello-framework
-│
-◇ What to title your project?
-│ Hello Framework
-│
-◆ Include sample files to help you get started?
-│ ● Yes, include sample files (recommended)
-│ ○ No, create an empty project
-└
-
-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.
-
-┌ observable create
-│
-◇ Where to create your project?
-│ hello-framework
-│
-◇ What to title your project?
-│ Hello Framework
-│
-◇ Include sample files to help you get started?
-│ Yes, include sample files
-│
-◆ Install dependencies?
-│ ○ Yes, via npm
-│ ● Yes, via yarn (recommended)
-│ ○ No
-└
-
-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`.
-
-┌ observable create
-│
-◇ Where to create your project?
-│ hello-framework
-│
-◇ What to title your project?
-│ Hello Framework
-│
-◇ Include sample files to help you get started?
-│ Yes, include sample files
-│
-◇ Install dependencies?
-│ Yes, via yarn
+◆ Welcome to Observable Framework! 👋 This command will help you create a new
+│ project. When prompted, you can press Enter to accept the default value.
│
-◆ Initialize a git repository?
-│ ● Yes / ○ No
-└
-
-And that’s it! After some downloading, copying, and installing, your new project is ready to go. 🎉
-
-┌ observable create
+│ Want help? https://observablehq.com/framework/getting-started
│
-◇ Where to create your project?
-│ hello-framework
+◇ Where should we create your project?
+│ ./hello-framework
│
-◇ What to title your project?
+◇ What should we title your project?
│ Hello Framework
│
◇ Include sample files to help you get started?
@@ -198,7 +130,9 @@ And that’s it! After some downloading, copying, and installing, your new proje
│ │
├────────────────────────╯
│
-└ Problems? https://observablehq.com/framework/getting-started
+└ Problems? https://github.com/observablehq/framework/discussions
+
+And that’s it! Your new project is ready to go. 🎉
## 2. Develop
@@ -533,7 +467,7 @@ _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:
npm run deploy
@@ -541,27 +475,9 @@ Or with Yarn:
yarn deploy
-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.
-
-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.
-
-Your deploy configuration is saved to docs/.observablehq/deploy.json. When collaborating on a project, you should commit this file to git so your collaborators don’t have to separately configure deploy.
-
-
-┌ observable deploy
-│
-● To configure deploy, we need to ask you a few questions.
-│
-◇ Deploying to the ACME Inc. (@acme) workspace.
-│
-◆ No projects found. Do you want to create a new project?
-│ ● Yes, continue / ○ No, cancel
-└
-
-
-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.
+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.
-When creating a new project, you need to specify a slug 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.
┌ observable deploy
@@ -569,38 +485,32 @@ When creating a new project, you need to specify a slug which — togethe
● To configure deploy, we need to ask you a few questions.
│
◇ Which Observable workspace do you want to use?
-│ ACME Inc. (@acme)
+│ ACME Inc. (@example)
│
◇ Which project do you want to use?
│ Create a new project
│
-◆ What slug do you want to use?
-│ hello-framework
-└
-
-
-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.
-
-
-┌ observable deploy
+◇ What slug do you want to use?
+│ hello-framework
│
-● To configure deploy, we need to ask you a few questions.
+◇ Who is allowed to access your project?
+│ Private
│
-◇ Which Observable workspace do you want to use?
-│ ACME Inc. (@acme)
+◇ What changed in this deploy?
+│ Enter a deploy message (optional)
│
-◇ Which project do you want to use?
-│ Create a new project
+◇ 18 uploaded
│
-◇ What slug do you want to use?
-│ hello-framework
+◇ Deploy complete
│
-◆ What changed in this deploy?
-│ Enter a deploy message (optional)
-└
+└ Deployed project now visible at https://example.observablehq.cloud/hello-framework/
-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.
+
+Your deploy configuration is saved to docs/.observablehq/deploy.json. When collaborating on a project, you should commit this file to git so your collaborators don’t have to separately configure deploy.
+
+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
diff --git a/docs/markdown.md b/docs/markdown.md
index c155c09cc..a458afeeb 100644
--- a/docs/markdown.md
+++ b/docs/markdown.md
@@ -235,7 +235,7 @@ The `note`, `tip`, `warning`, and `caution` classes can be used to insert labele
This is a caution.
```
-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 ``) are interpreted as HTML. For rich formatting or links within a note, use HTML.
This is a styled tip using HTML.
@@ -247,6 +247,22 @@ Markdown is not supported within HTML, so if you want rich formatting or links w
```
+Alternatively, use blank lines to separate the contents of the note from the note container, and then the contents will be interpreted as Markdown.
+
+
+
+This is a *styled* tip using **Markdown**.
+
+
+
+```md run=false
+
+
+This is a *styled* tip using **Markdown**.
+
+
+```
+
You can override the note’s label using the `label` attribute.
No lifeguard on duty. Swim at your own risk!
diff --git a/src/convert.ts b/src/convert.ts
index 8379dd22c..8c86339f4 100644
--- a/src/convert.ts
+++ b/src/convert.ts
@@ -41,7 +41,7 @@ export async function convert(
effects: ConvertEffects = defaultEffects
): Promise
{
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();
diff --git a/src/create.ts b/src/create.ts
index 10ad1118e..d4c090ec7 100644
--- a/src/create.ts
+++ b/src/create.ts
@@ -39,20 +39,26 @@ const defaultEffects: CreateEffects = {
export async function create(effects: CreateEffects = defaultEffects): Promise {
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!)
}),
@@ -131,7 +137,7 @@ export async function create(effects: CreateEffects = defaultEffects): Promise 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")}`);
}
},
{
diff --git a/src/deploy.ts b/src/deploy.ts
index 708e99c27..cd240e914 100644
--- a/src/deploy.ts
+++ b/src/deploy.ts
@@ -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;
@@ -79,7 +79,7 @@ export async function deploy(
): Promise {
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});
diff --git a/src/observableApiAuth.ts b/src/observableApiAuth.ts
index 08b85ec56..2b0f55845 100644
--- a/src/observableApiAuth.ts
+++ b/src/observableApiAuth.ts
@@ -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();
@@ -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);