From 92261d19cb42d34e6c6d5fd5fe9f99f648bc162f Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Mon, 11 Aug 2025 18:42:54 -0600 Subject: [PATCH 01/26] save --- sites/create-a-site.md | 2 +- start/getting-started/install-cli.md | 76 ++++++++++++++++++++++++++++ start/index.md | 68 ++++++++++++------------- 3 files changed, 110 insertions(+), 36 deletions(-) create mode 100644 start/getting-started/install-cli.md diff --git a/sites/create-a-site.md b/sites/create-a-site.md index cd40544..d7d4872 100644 --- a/sites/create-a-site.md +++ b/sites/create-a-site.md @@ -7,7 +7,7 @@ short_title: Create a Site Get started creating a publishing destination for your articles, lab notebooks, or group collections. ::: -## Steps to Set Up a Site +## Steps to Set Up a Site!! :::{important} Before you start Make sure you have: diff --git a/start/getting-started/install-cli.md b/start/getting-started/install-cli.md new file mode 100644 index 0000000..e301c84 --- /dev/null +++ b/start/getting-started/install-cli.md @@ -0,0 +1,76 @@ + +# Install & Authenticate the Curvenote CLI + +**Goal:** Install the Curvenote command-line tool, log in, and ensure you're ready to create and publish content. + + + +## Prerequisites + +Before installing the CLI, make sure you have: + +- **Node.js v18 or later** (comes with `npm`) + - Check your version: + ```bash + node --version + ``` + - If needed, [download Node.js](https://nodejs.org/) or install via Conda: + ```bash + conda install -c conda-forge nodejs + ``` + + + +## 1. Install the CLI + +Open your terminal and run: + +```bash +npm install -g curvenote + +``` +After installation, verify the CLI is installed: +```bash +curvenote --version +``` +You should see a version number (e.g., `0.1.2`). +If you see an error, check your Node.js and `npm` setup. + +## 2. Authenticate with Curvenote +Run the login command: +```bash +curvenote login +``` +1. Your browser will open to the Curvenote sign-in page. + +2. Sign in with your Curvenote account. + +3. Once you return to the terminal, you should see a confirmation message like: +``` +Logged in as +``` + +If you use multiple accounts, you can switch by running: +```bash +curvenote token select +``` +## 3. Verify Your Setup +To confirm you’re ready to go: +```bash +curvenote whoami +``` + +If it returns your username, your CLI is authenticated and ready. + + +## Next Steps + +Now that you’ve installed and authenticated the CLI, you can: + +1. [Create Your First Project →](../getting-started/organize-content.md) +2. [Write Your First Article →](../how-to/create-article-cli.md) +3. [Publish & Share →](../how-to/publish-article.md) + +--- + +**Tip:** The Curvenote CLI is open source—[view it on GitHub](https://github.com/curvenote/curvenote). diff --git a/start/index.md b/start/index.md index 6021bdf..f0f0481 100644 --- a/start/index.md +++ b/start/index.md @@ -1,56 +1,54 @@ # What is Curvenote? -Curvenote is a platform for writing, organizing, and publishing scientific content—built by researchers, for researchers. +Curvenote is a platform for **writing, organizing, and publishing scientific content**—built by researchers, for researchers. -It helps you move beyond static PDFs by enabling interactive, modular, and versioned scientific outputs. Whether you're drafting a preprint, creating a lab website, or sharing reproducible analyses, Curvenote provides the tools to publish with structure, transparency, and flexibility. +It helps you move beyond static PDFs by enabling **interactive, modular, and versioned scientific outputs**. Whether you're drafting a preprint, creating a lab website, or sharing reproducible analyses, Curvenote provides the tools to publish with **structure, transparency, and flexibility**. ## A new kind of scientific output -Most research outputs today are frozen in time—locked into PDFs and detached from the data, code, or figures that created them. Curvenote enables a different approach: +Most research outputs today are frozen in time—locked into PDFs and detached from their underlying data, code, and figures. Curvenote takes a different approach: -- Modular articles with reusable blocks and components -- Versioned content that captures draft history and changes -- Web-first publishing that prioritizes discoverability -- Integrated exports to Typst and PDF when needed +- **Modular articles** with reusable blocks and components +- **Versioned content** that tracks every change +- **Web-first publishing** for better discoverability +- **One-click exports** to Typst or PDF when needed -## Write once, publish anywhere -Curvenote works in your browser or with the Curvenote CLI. You can: +Work in your browser or use the Curvenote CLI: -- Write in Markdown, Jupyter, or the Curvenote editor -- Organize content into folders, articles, and blocks -- Connect to GitHub for version control and collaboration -- Publish to the web with a single command -- Export to Typst or PDF for review or submission +- Write in **Markdown, Jupyter**, or the Curvenote editor +- Organize content into **folders, articles, and blocks** +- Connect to **GitHub** for version control and collaboration +- Publish to the web with a single command +- Export to Typst or PDF for review or submission -## Publishing is part of your workflow +--- -Publishing with Curvenote is fast and flexible. You can publish: +## Publishing as part of your workflow +Publishing with Curvenote is fast and flexible. You can publish: -- Single articles -- Multi-article collections (like lab sites or documentation) -- Research outputs with interactive figures, notebooks, and citations +- Single articles +- Multi-article collections (lab sites, conference proceedings, documentation) +- Research outputs with **interactive figures, notebooks, and citations** -Everything you publish remains editable and updateable—no reformatting required. +Everything you publish stays editable and updateable—no reformatting required. -## Built for research teams -Curvenote supports: +## Built for research teams +Curvenote supports: -- Collaborative editing and version tracking -- Reusable figures, text blocks, and citations -- DOI minting and metadata support -- Automated research integrity checks (iThenticate, Proofig) -- Compliance with open science, funder, and institutional policies +- Collaborative editing & version tracking +- Reusable figures, text blocks, and citations +- DOI minting & metadata management +- Research integrity checks (iThenticate, Proofig) +- Compliance with open science, funder, and institutional policies -## Why it matters -Scientific knowledge should be open, versioned, and reusable. Curvenote is designed to support modern scientific communication by providing infrastructure for living research outputs. +## Why it matters +Scientific knowledge should be **open, versioned, and reusable**. Curvenote provides the infrastructure for **living research outputs**—helping you move faster, stay organized, and share work in ways that are valuable to both humans and machines. -Whether you're preparing a funder report, publishing a preprint, or launching a public-facing project, Curvenote helps you move faster, stay organized, and share your work in ways that are meaningful to both humans and machines. -## Next steps - -- [Install the CLI](../cli/index.md) -- [Set up your first publishing site](../sites/index.md) -- [Write and publish your first article](../authoring/index.md) +## Next steps +1. [Install the CLI](install-cli.md) +2. [Set up your first publishing site](set-up-site.md) +3. [Write and publish your first article](create-article-cli.md) \ No newline at end of file From d5a394b1162a38eb15c4c837e847f8dec5a48605 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Mon, 11 Aug 2025 20:10:52 -0600 Subject: [PATCH 02/26] updated articles --- .DS_Store | Bin 0 -> 6148 bytes myst.yml | 4 + start/.DS_Store | Bin 0 -> 6148 bytes start/getting-started/create-article-cli.md | 96 +++++++++++++++++ start/getting-started/organize-content.md | 109 +++++++++++++++++++ start/getting-started/publish-article.md | 63 +++++++++++ start/organize-content.md | 110 ++++++++++++++++++++ 7 files changed, 382 insertions(+) create mode 100644 .DS_Store create mode 100644 start/.DS_Store create mode 100644 start/getting-started/create-article-cli.md create mode 100644 start/getting-started/organize-content.md create mode 100644 start/getting-started/publish-article.md create mode 100644 start/organize-content.md diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..7acf9a758aa4614186382802c6231163ec1b37db GIT binary patch literal 6148 zcmeHKI|>3Z5S{S@f{mqRuHX%V=n3`$3WAL&_^Y?_TprCgpJrL?v{2r_^;wp)nIL}UUtl!py{vwicP4KkuYIL^4Hg$K#o*^3Un11#&Tx$e+_@r z|944TQ2{FOR|@E8)vT6yQr6bqi80h5~3oFNSPl~)^bL`i| UHqhyaI~~ZM0n>#>1-`Ao3)Y4d=l}o! literal 0 HcmV?d00001 diff --git a/myst.yml b/myst.yml index 4b2d76a..ca904c7 100644 --- a/myst.yml +++ b/myst.yml @@ -43,6 +43,10 @@ project: - title: Getting Started children: - file: start/index.md + - file: start/getting-started/install-cli.md + - file: start/getting-started/organize-content.md + - file: start/getting-started/create-article-cli.md + - file: start/getting-started/publish-article.md - title: Site design children: - file: sites/index.md diff --git a/start/.DS_Store b/start/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..efc4b9c3010167a291cf4cbb613ec2957d716b09 GIT binary patch literal 6148 zcmeHK!D`z;5S?}0L?)E_&_Hrq=+&jJTVhHt!byIhD$SuOu2hLcRMiGct`5ead-6m1 zk$g|y>~2hg(_1OU%)rbW&(28RH?XTAA~l((Z;ARu6hIj}J(wqi*IC!3<0D%@WuK8# zN$2#MDyrAACGbBoz`c8co@MA*O%MAQ(+rV}(zNTWY8EVktnoQDEmq}p~ z#BY+zBCqP<@K$xUy3e+Ef}LPD_!eE5CaU9lUQOcJSN`=G4@&O+IQf!i&9wjW$dq-Q zm)Xn~_@gC3?Gr+SSq|f*N$)D$cn@s($mOeeA8G}0%?>d1*g8Z6A|C>l1~J0G HKV{$!ELl^x literal 0 HcmV?d00001 diff --git a/start/getting-started/create-article-cli.md b/start/getting-started/create-article-cli.md new file mode 100644 index 0000000..a8d374e --- /dev/null +++ b/start/getting-started/create-article-cli.md @@ -0,0 +1,96 @@ +# Write Your First Article + +**Goal:** Create and edit your first article in Curvenote using the CLI. + + + +## 1. Create a New Article + +From inside your project folder, run: + +```bash +curvenote create article my-first-article +``` + +This will: + +- Create a new Markdown file in your `content/` directory. +- Add default frontmatter (metadata) like `title` and `date`. +- Link the article into your site navigation if your `curvenote.yml` is set up. + +Example folder after running the command: + +``` +content/ +├── index.md +└── my-first-article.md +``` + + + +## 2. Open and Edit Your Article + +Open the new file in your preferred text editor: + +```bash +code content/my-first-article.md +``` + +You can write in **Markdown**, **MyST**, or embed Jupyter code blocks if your project supports it. + +Example content: + +```markdown +--- +title: My First Curvenote Article +authors: + - name: Jane Doe + orcid: 0000-0001-2345-6789 +--- + +# Introduction + +This is my first article written in Curvenote! 🎉 + +## My First Figure + +```{figure} assets/fig1.png +:alt: Example figure +:width: 60% +``` +Figure caption goes here. + + +## 3. Preview Locally + +See your changes instantly by running: + +```bash +curvenote preview +``` + +This opens a local preview of your site in your browser so you can check formatting, figures, and links. + + + +## 4. Organize Your Articles + +Best practices for keeping articles manageable: + +- Use short, descriptive file names. +- Group related content into folders (e.g., `methods/`, `results/`). +- Keep figures, datasets, and large media files in an `assets/` folder. + + + +## Next Steps + +Once your article looks good, you can: + +1. [Publish & Share →](./publish-article.md) +2. [Add Figures, Images, and Media →](../authoring/add-figures-media.md) +3. [Link Data and Code →](../authoring/link-data-code.md) + +--- + +**Tip:** Curvenote supports reusable content blocks, so you can keep figures, citations, or sections consistent across multiple articles. diff --git a/start/getting-started/organize-content.md b/start/getting-started/organize-content.md new file mode 100644 index 0000000..199d438 --- /dev/null +++ b/start/getting-started/organize-content.md @@ -0,0 +1,109 @@ +# Create Your First Project + +**Goal:** Create and organize your first Curvenote project so you can start writing and publishing content. + + + +## 1. What’s a Project in Curvenote? + +A **project** is the home for your articles, figures, datasets, and other content. +It also stores your site configuration so you can publish to the web. + +Projects contain: + +- **Content folder** (`content/`) for articles, sections, and figures. +- **Configuration file** (`curvenote.yml`) for site and article settings. +- **Assets folder** for images, datasets, and other media. + + + +## 2. Create a New Project + +From your terminal: + +```bash +curvenote init my-first-project +``` + +You’ll be prompted to: + +1. **Name your project** + Example: `My Lab Website` or `My Article` +2. **Add an optional description** +3. Confirm your configuration. + +This creates a folder with the following structure: + +``` +my-first-project/ +├── content/ +│ └── index.md +├── curvenote.yml +└── README.md +``` + + +## 3. Navigate and Explore + +Move into your new project folder: + +```bash +cd my-first-project +``` + +Open `content/index.md` in your editor — this is your first article. +You can rename it, add more `.md` or `.myst.md` files, and create subfolders for sections. + + + +## 4. Organize Your Content + +Best practices: + +- **One article per file** for clarity. +- Group related articles into folders (e.g., `/methods`, `/results`). +- Keep images and figures in an `/assets` folder. +- Use clear, short file names (avoid spaces). + +Example: + +``` +content/ +├── introduction.md +├── methods/ +│ ├── data-collection.md +│ └── analysis.md +├── results/ +│ ├── experiment-1.md +│ └── experiment-2.md +└── assets/ + ├── fig1.png + └── dataset.csv +``` + + + +## 5. Check Your Setup + +You can preview your content locally by running: + +```bash +curvenote preview +``` + +This launches a local development server where you can see your project as it will appear online. + + + + +## Next Steps + +Now that you have a project: + +1. [Write Your First Article →](../how-to/create-article-cli.md) +2. [Publish & Share →](../how-to/publish-article.md) +3. [Set Up a Site →](../getting-started/set-up-site.md) + +--- + +**Tip:** You can connect your project to GitHub for version control. See [Connect to GitHub](../integrations/github.md). \ No newline at end of file diff --git a/start/getting-started/publish-article.md b/start/getting-started/publish-article.md new file mode 100644 index 0000000..81d6d1e --- /dev/null +++ b/start/getting-started/publish-article.md @@ -0,0 +1,63 @@ +# Publish & Share + +**Goal:** Publish your article or site so it’s live on the web. + + + +## 1. Make Sure Your Project Is Ready + +Before publishing, confirm that your project has: + +- At least one article with content. +- A valid `curvenote.yml` configuration file. +- Any required assets (figures, datasets, notebooks) included in the project. + +If you’re not sure your site is configured, see: +[Set Up a Site →](../getting-started/set-up-site.md) + + + +## 2. Publish from the CLI + +Run the publish command from your project folder: + +```bash +curvenote publish +``` + +You’ll see output confirming which articles or collections are being published and the URL where your content will appear. + + + +## 3. View Your Live Site + +Once publishing finishes, the CLI will display a URL to your live site. +Open it in your browser to verify: + +- Formatting and layout look correct. +- Figures, tables, and media load properly. +- Links and citations work as expected. + + + +## 4. Update Published Content + +If you make changes to your articles, simply run: + +```bash +curvenote publish +``` + +Curvenote will update the existing content without requiring you to start over. + + + +## Next Steps + +- [Add Figures, Images, and Media →](../authoring/add-figures-media.md) +- [Link Data and Code →](../authoring/link-data-code.md) +- [Export to PDF/Typst →](../tutorials/export-pdf.md) + +--- + +**Tip:** Published content is “living” in Curvenote — you can make edits anytime, and your audience will always see the latest version. \ No newline at end of file diff --git a/start/organize-content.md b/start/organize-content.md new file mode 100644 index 0000000..338a7ce --- /dev/null +++ b/start/organize-content.md @@ -0,0 +1,110 @@ +# Create Your First Project + +**Goal:** Create and organize your first Curvenote project so you can start writing and publishing content. + + + +## 1. What’s a Project in Curvenote? + +A **project** is the home for your articles, figures, datasets, and other content. +It also stores your site configuration so you can publish to the web. + +Projects contain: + +- **Content folder** (`content/`) for articles, sections, and figures. +- **Configuration file** (`curvenote.yml`) for site and article settings. +- **Assets folder** for images, datasets, and other media. + + + +## 2. Create a New Project + +From your terminal: + +```bash +curvenote init my-first-project +``` + +You’ll be prompted to: + +1. **Name your project** + Example: `My Lab Website` or `My Article` +2. **Add an optional description** +3. Confirm your configuration. + +This creates a folder with the following structure: + +``` +my-first-project/ +├── content/ +│ └── index.md +├── curvenote.yml +└── README.md +``` + + +## 3. Navigate and Explore + +Move into your new project folder: + +```bash +cd my-first-project +``` + +Open `content/index.md` in your editor — this is your first article. +You can rename it, add more `.md` or `.myst.md` files, and create subfolders for sections. + + + +## 4. Organize Your Content + +Best practices: + +- **One article per file** for clarity. +- Group related articles into folders (e.g., `/methods`, `/results`). +- Keep images and figures in an `/assets` folder. +- Use clear, short file names (avoid spaces). + +Example: + +``` +content/ +├── introduction.md +├── methods/ +│ ├── data-collection.md +│ └── analysis.md +├── results/ +│ ├── experiment-1.md +│ └── experiment-2.md +└── assets/ + ├── fig1.png + └── dataset.csv +``` + + + +## 5. Check Your Setup + +You can preview your content locally by running: + +```bash +curvenote preview +``` + +This launches a local development server where you can see your project as it will appear online. + + + + +## Next Steps + +Now that you have a project: + +1. [Write Your First Article →](../how-to/create-article-cli.md) +2. [Publish & Share →](../how-to/publish-article.md) +3. [Set Up a Site →](../getting-started/set-up-site.md) + +--- + +**Tip:** You can connect your project to GitHub for version control. See [Connect to GitHub](../integrations/github.md). +``` \ No newline at end of file From e00dcf25c889f6e23344fae3b6b99470f8db2439 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Tue, 12 Aug 2025 10:17:43 -0600 Subject: [PATCH 03/26] create a site --- .../create-a-site.md | 162 ++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 start/Design-&-Customize-Your-Site/create-a-site.md diff --git a/start/Design-&-Customize-Your-Site/create-a-site.md b/start/Design-&-Customize-Your-Site/create-a-site.md new file mode 100644 index 0000000..5e3a97f --- /dev/null +++ b/start/Design-&-Customize-Your-Site/create-a-site.md @@ -0,0 +1,162 @@ +--- +title: How to Set Up a Publishing Site in Curvenote +short_title: Create a Site +--- + + + +# Create a Site + +:::{tip} ObjectiveCreate a publishing destination for your articles, lab notebooks, or group collections. ::: + +## Quick Checklist + +- Have a Curvenote account & CLI installed +- Access or create a site (web admin) +- Configure your project (curvenote.yml) +- Organize local content (if using Git/GitHub) +- Add metadata to each file +- Submit content to a site & collection +- Push changes for internal review (optional) +- Run checks before publishing (optional) +- Publish (admin only) + +## Workflow at a Glance + +```mermaid +graph TD + A[1. Create Site
web admin] --> B[2. Set Landing Page] + B --> C[3. Organize Content
optional for local/Git] + C --> D[4. Add Metadata] + D --> E[5. Submit Content] + E --> F[6. Push Changes
optional] + F --> G[7. Run Checks
optional] + G --> H[8. Publish
admin only] + H --> I[🎉 Site Live!] + + style A fill:#e1f5fe + style I fill:#c8e6c9 +``` + +**Text Version:** + +``` +[1] Create Site (web admin) + ↓ +[2] Set Landing Page + ↓ +[3] Organize Content (optional for local/Git) + ↓ +[4] Add Metadata + ↓ +[5] Submit Content → [6] Push Changes (optional) + ↓ +[7] Run Checks (optional) + ↓ +[8] Publish (admin only) + ↓ + 🎉 Site Live! +``` + ## Before You Begin +:::{important} Make sure you have: + +- A Curvenote account and Curvenote CLI installed +- Access to an existing site (or permission to create one via the web admin interface) +- A configured project (curvenote.yml) if publishing from GitHub or locally +::: + + +### 1. Create a Site (via Web Admin) + +Currently, new sites must be created through the web admin interface. + +- Choose a title and subdomain (e.g., `my-lab.curve.space`) +- Set the site visibility (public or private) +- Define the organization or group that owns the site + +_Coming Soon: Site creation directly from the CLI._ + +### 2. Set a Landing Page or Featured Work + +Once the site exists, an admin can define a “landing page” — the main entry point for visitors. + +- Recommended: Set this via the web admin interface +- CLI support available for some workflows + +### 3. Organize Your Content (Optional, CLI or Git-based Workflows) + +If you are managing content locally (e.g., in GitHub), organize your files into logical directories: + +- **Full Research Articles:** `articles/` +- **Figures/Methods:** `components/` +- **Landing page:** `index.md` + +For sites with community submissions, content organization happens after submission. + +### 4. Add Metadata + +Each content file should have frontmatter with key details: + +```yaml +--- +title: 'An Advanced Microscopy Study' +authors: + - name: Dr. Lee +kind: article +--- +``` + +Metadata enables automated checks, collection assignment, and proper formatting + +### 5. Submit Content to a Site and Collection + +From your local project, run: + +```bash +curvenote submit +``` + +You’ll be prompted to: + +- Select an existing site +- Choose a collection (e.g., "Lab Articles") + +This prepares your content for publishing and notifies site administrators. + +### 6. Push Changes (Optional: Internal Review) + +```bash +curvenote push +``` + +This allows collaborators to preview your work, but does not make it publicly visible. + +### 7. Run Checks (Optional but Recommended) + + +```bash +curvenote check +``` + +This will run structural and metadata checks and highlight any issues. + +> 💡 **Tip:** For more details on how to run a structural check, visit this page (link) + +### 8. Publish Content (Admin Action) + +Publishing makes submitted content live on the site: + +```bash +curvenote submission publish +``` + +Only site admins can publish. Once published: + +- Content appears on the site +- DOI, metadata, and links are activated + +## After Publishing + +- Share links to your articles or site homepage +- Updates and re-publish (each update is tracked) +- Embed individual figures, notebooks, or methods in other sites and tools. From 4946578a570f5a67176a89840d80ef927bea6a29 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Tue, 12 Aug 2025 16:07:12 -0600 Subject: [PATCH 04/26] Update table of contents structure --- .DS_Store | Bin 6148 -> 10244 bytes {start => Getting Started}/.DS_Store | Bin 6148 -> 6148 bytes .../create-a-site.md | 0 .../create-article-cli.md | 6 + .../create-project.md | 5 + .../install-cli.md | 4 + .../publish-article.md | 6 + .../what-is-curvenote.md | 5 + myst.yml | 44 +++---- sites/create-a-site.md | 120 ------------------ start/organize-content.md | 110 ---------------- 11 files changed, 47 insertions(+), 253 deletions(-) rename {start => Getting Started}/.DS_Store (90%) rename {start/Design-&-Customize-Your-Site => Getting Started}/create-a-site.md (100%) rename {start/getting-started => Getting Started}/create-article-cli.md (96%) rename start/getting-started/organize-content.md => Getting Started/create-project.md (97%) rename {start/getting-started => Getting Started}/install-cli.md (95%) rename {start/getting-started => Getting Started}/publish-article.md (95%) rename start/index.md => Getting Started/what-is-curvenote.md (97%) delete mode 100644 sites/create-a-site.md delete mode 100644 start/organize-content.md diff --git a/.DS_Store b/.DS_Store index 7acf9a758aa4614186382802c6231163ec1b37db..e3373b57ce51d6cccbfbfe3a2c55edb6720e971d 100644 GIT binary patch literal 10244 zcmeHNO>Y}T7@l=f*T!i`3aw~SrIolK6o(`&aS#_1iV#AJf@XDdin!gMFoZrBn?k z<<9%X}brG0mp!2z%k$$a18t(7{Hp%qt?*U zT^$3C0ms0C0oDf}CuKXAGcBcb;38W9$aOrH18wXB1mowjoy(b)0)6omv1pV z4aa+*>X7YR&a~8UKJegEHl8pdsTH+pfVK}_U}xk z4{`4PEr)}1CwqH;c$KyFYt`$u>$OJho6c!6?M!-;EIsaxzvA8J zNfHI~b}#rM98SAiuYZ)plU^7P#{vikL#TZHWf%{V>2Z?9gH*5`{i0T{)w^4FE-nsQ zt%Du^pmlh;<6pdgu(#tsxPN$gS+CuC>)j7N>pqD_aq@!^V<19cBjB32@5?P$w} zTg;}18FGH+d`o92f%UTySht^Pk?aj&wcHjNH*MX6zlIoF1h$?oJU2o+#Ymg#5iBL} zToWD*h1CoRu*wgnm z`>Of`+7tYA#QLg(w)P0D*l2pe+cdmz1=>jX-=2HI-$lY7zIU|aH}_ljnej&taC6k! zFJwG38pq0v{|PUznCDUrFyrJuc{J^BN>n})M!1sp$suMH z038&tms9d6|<&|Ye2G|E_sd&R=%|uB+rrb5t4BkXX&bM z;ogKE862S>X8j!7#8ckse@&QmrDWXX+Ok^5m`^e4QO?)WI9L}f#5NGDH_Rqxv|h1v zT$Sb&S0Bs58?azA%#8kbeQkmrM&&cOx9r`$(jIG8f(X~EYzZ&orQZ!N-72xkYLrQA zok|uA$|8f6x?)Cemnx3BDfc$v%-~V5165Q+@11~uP-ulDN!()&z z|3+5igWuYHoZsQ(LA{xl0>MQ-$3x2Jc--)F{M$IGyGO|b?RG9_TH*OrU5E*g6oM$$-Tq21g!bqb8d( veQ_3HC}+q3J4F|$sTk>Pjj0koMI0RR91 diff --git a/start/Design-&-Customize-Your-Site/create-a-site.md b/Getting Started/create-a-site.md similarity index 100% rename from start/Design-&-Customize-Your-Site/create-a-site.md rename to Getting Started/create-a-site.md diff --git a/start/getting-started/create-article-cli.md b/Getting Started/create-article-cli.md similarity index 96% rename from start/getting-started/create-article-cli.md rename to Getting Started/create-article-cli.md index a8d374e..6fa5cc6 100644 --- a/start/getting-started/create-article-cli.md +++ b/Getting Started/create-article-cli.md @@ -1,3 +1,9 @@ +--- +title: Write Your First Article +short_title: Write Article +--- + + # Write Your First Article **Goal:** Create and edit your first article in Curvenote using the CLI. diff --git a/start/getting-started/organize-content.md b/Getting Started/create-project.md similarity index 97% rename from start/getting-started/organize-content.md rename to Getting Started/create-project.md index 199d438..c9a4f18 100644 --- a/start/getting-started/organize-content.md +++ b/Getting Started/create-project.md @@ -1,3 +1,8 @@ +--- +title: Create Your First Project +short_title: Create Project +--- + # Create Your First Project **Goal:** Create and organize your first Curvenote project so you can start writing and publishing content. diff --git a/start/getting-started/install-cli.md b/Getting Started/install-cli.md similarity index 95% rename from start/getting-started/install-cli.md rename to Getting Started/install-cli.md index e301c84..d34be54 100644 --- a/start/getting-started/install-cli.md +++ b/Getting Started/install-cli.md @@ -1,3 +1,7 @@ +--- +title: Install & Authenticate the Curvenote CLI +short_title: Install CLI +--- # Install & Authenticate the Curvenote CLI diff --git a/start/getting-started/publish-article.md b/Getting Started/publish-article.md similarity index 95% rename from start/getting-started/publish-article.md rename to Getting Started/publish-article.md index 81d6d1e..a4daa82 100644 --- a/start/getting-started/publish-article.md +++ b/Getting Started/publish-article.md @@ -1,3 +1,9 @@ +--- +title: Publish & Share Your Article +short_title: Publish & Share +--- + + # Publish & Share **Goal:** Publish your article or site so it’s live on the web. diff --git a/start/index.md b/Getting Started/what-is-curvenote.md similarity index 97% rename from start/index.md rename to Getting Started/what-is-curvenote.md index f0f0481..ccbbbe1 100644 --- a/start/index.md +++ b/Getting Started/what-is-curvenote.md @@ -1,3 +1,8 @@ +--- +title: What is Curvenote? +short_title: What is Curvenote +--- + # What is Curvenote? Curvenote is a platform for **writing, organizing, and publishing scientific content**—built by researchers, for researchers. diff --git a/myst.yml b/myst.yml index ca904c7..8bbb2ec 100644 --- a/myst.yml +++ b/myst.yml @@ -42,31 +42,29 @@ project: - file: solutions.md - title: Getting Started children: - - file: start/index.md - - file: start/getting-started/install-cli.md - - file: start/getting-started/organize-content.md - - file: start/getting-started/create-article-cli.md - - file: start/getting-started/publish-article.md - - title: Site design + - file: getting-started/What-is-curvenote.md + - file: getting-started/install-cli.md + - file: getting-started/create-project.md + - file: getting-started/create-article-cli.md + - file: getting-started/publish-article.md + - file: getting-started/create-a-site.md + - title: Design & Customize Your Site children: - - file: sites/index.md - - file: sites/concepts.md - - file: sites/create-a-site.md - - file: sites/landing-pages.md - - file: sites/navigation.md - - file: sites/cards.md - - file: sites/listings.md - - file: sites/custom-domains.md - - file: sites/curvenote-branding.md - - file: sites/analytics.md - - file: sites/custom-development.md - - title: Preparing articles + - file: site-design/layout-and-theme.md + - file: site-design/planning.md + - file: site-design/custom-domains.md + - file: site-design/navigation.md + - title: Authoring Content children: - - file: authoring/myst-markdown.md - - file: article-actions.md - - file: authoring/submitting-your-work.md - - file: tutorial-deploy-local.md - - file: try-curvespace.md + - file: authoring/citations.md + - file: authoring/add-figures-media.md + - file: authoring/interactive-figures.md + - file: authoring/link-data-code.md + - file: authoring/organize-content.md + - file: authoring/reuse-blocks.md + - file: authoring/version-history.md + - file: authoring/writing-markdown-myst-jupyter.md + - title: Computational articles children: - file: computational-articles.md diff --git a/sites/create-a-site.md b/sites/create-a-site.md deleted file mode 100644 index d7d4872..0000000 --- a/sites/create-a-site.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: How to Set Up a Publishing Site in Curvenote -short_title: Create a Site ---- - -:::{tip} Objective -Get started creating a publishing destination for your articles, lab notebooks, or group collections. -::: - -## Steps to Set Up a Site!! - -:::{important} Before you start -Make sure you have: - -- A Curvenote account and access to the [Curvenote CLI](../cli/index.md) -- Access to an existing site (or create one via the web admin interface) -- A configured project (`curvenote.yml` file) if publishing from GitHub or locally - ::: - -### 1. Create a Site (via Web Admin) - -Creating a new site must currently be done through the web admin interface. - -- Choose a title and subdomain (e.g., `my-lab.curve.space`) -- Set the site visibility (public or private) -- Define the organization or group that owns the site - -_Coming Soon: CLI-based site creation is planned to make this easier for new users._ - -### 2. Set a Landing Page or Featured Work - -Once the site exists, site administrators can set a "landing page" or featured work. This may be configured via: - -- The web admin interface (recommended) -- CLI tools (if supported) - -The landing page gives visitors an entry point to your site’s most important content. - -### 3. Organize Your Content (Optional, CLI or Git-based Workflows) - -If you are managing content locally (e.g., in GitHub), organize your files into logical directories: - -- **Articles:** `articles/` -- **Figures/Methods:** `components/` -- **Landing page:** `index.md` - -For sites that accept community contributions or external submissions, this structure will be handled post-submission. - -### 4. Add Metadata and Content Types (Kinds) - -Ensure that each content file includes a frontmatter block with relevant metadata: - -```yaml ---- -title: 'An Advanced Microscopy Study' -authors: - - name: Dr. Lee -kind: article ---- -``` - -This metadata supports automated checks, collection assignment, and proper formatting. - -### 5. Submit Content to a Site and Collection - -Use the CLI to associate your content with a site and collection: - -```bash -curvenote submit -``` - -You’ll be prompted to: - -- Select an existing site -- Choose a collection (e.g., "Lab Articles") - -This prepares your content for publishing and notifies site administrators. - -### 6. Push Changes to the Server (Optional) - -To sync your draft content to the server for internal review: - -```bash -curvenote push -``` - -This allows collaborators to preview your work, but does not make it publicly visible. - -### 7. Run Structural Checks (Optional) - -To verify your content is valid before publishing: - -```bash -curvenote check -``` - -This will run structural and metadata checks and highlight any issues. - -> 💡 **Tip:** For more details on how to run a structural check, visit this page (link) - -### 8. Publish Content (Admin Action) - -Publishing makes submitted content live on the site: - -```bash -curvenote submission publish -``` - -Only site admins can publish submitted content. Once published: - -- Content appears on the site -- DOI, metadata, and links are activated - -## What Happens Next? - -Once published, you can: - -- Share links to your articles or site homepage -- Make updates and re-publish (each update is versioned) -- Embed content elsewhere (figures, notebooks, methods) diff --git a/start/organize-content.md b/start/organize-content.md deleted file mode 100644 index 338a7ce..0000000 --- a/start/organize-content.md +++ /dev/null @@ -1,110 +0,0 @@ -# Create Your First Project - -**Goal:** Create and organize your first Curvenote project so you can start writing and publishing content. - - - -## 1. What’s a Project in Curvenote? - -A **project** is the home for your articles, figures, datasets, and other content. -It also stores your site configuration so you can publish to the web. - -Projects contain: - -- **Content folder** (`content/`) for articles, sections, and figures. -- **Configuration file** (`curvenote.yml`) for site and article settings. -- **Assets folder** for images, datasets, and other media. - - - -## 2. Create a New Project - -From your terminal: - -```bash -curvenote init my-first-project -``` - -You’ll be prompted to: - -1. **Name your project** - Example: `My Lab Website` or `My Article` -2. **Add an optional description** -3. Confirm your configuration. - -This creates a folder with the following structure: - -``` -my-first-project/ -├── content/ -│ └── index.md -├── curvenote.yml -└── README.md -``` - - -## 3. Navigate and Explore - -Move into your new project folder: - -```bash -cd my-first-project -``` - -Open `content/index.md` in your editor — this is your first article. -You can rename it, add more `.md` or `.myst.md` files, and create subfolders for sections. - - - -## 4. Organize Your Content - -Best practices: - -- **One article per file** for clarity. -- Group related articles into folders (e.g., `/methods`, `/results`). -- Keep images and figures in an `/assets` folder. -- Use clear, short file names (avoid spaces). - -Example: - -``` -content/ -├── introduction.md -├── methods/ -│ ├── data-collection.md -│ └── analysis.md -├── results/ -│ ├── experiment-1.md -│ └── experiment-2.md -└── assets/ - ├── fig1.png - └── dataset.csv -``` - - - -## 5. Check Your Setup - -You can preview your content locally by running: - -```bash -curvenote preview -``` - -This launches a local development server where you can see your project as it will appear online. - - - - -## Next Steps - -Now that you have a project: - -1. [Write Your First Article →](../how-to/create-article-cli.md) -2. [Publish & Share →](../how-to/publish-article.md) -3. [Set Up a Site →](../getting-started/set-up-site.md) - ---- - -**Tip:** You can connect your project to GitHub for version control. See [Connect to GitHub](../integrations/github.md). -``` \ No newline at end of file From de756da9564d5d49b2c4be821122702407ef73b6 Mon Sep 17 00:00:00 2001 From: Franklin Koch Date: Wed, 13 Aug 2025 02:16:49 -0600 Subject: [PATCH 05/26] Small changes to fix file paths --- .gitignore | 1 + Getting Started/.DS_Store | Bin 6148 -> 0 bytes .../create-a-site.md | 0 .../create-article-cli.md | 0 .../create-project.md | 0 .../install-cli.md | 0 .../publish-article.md | 0 .../what-is-curvenote.md | 0 myst.yml | 4 ++-- 9 files changed, 3 insertions(+), 2 deletions(-) delete mode 100644 Getting Started/.DS_Store rename {Getting Started => getting-started}/create-a-site.md (100%) rename {Getting Started => getting-started}/create-article-cli.md (100%) rename {Getting Started => getting-started}/create-project.md (100%) rename {Getting Started => getting-started}/install-cli.md (100%) rename {Getting Started => getting-started}/publish-article.md (100%) rename {Getting Started => getting-started}/what-is-curvenote.md (100%) diff --git a/.gitignore b/.gitignore index 241e57a..e27c7d8 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ content/jupyter/images content/overview/images content/export/images content/web/images +.DS_Store \ No newline at end of file diff --git a/Getting Started/.DS_Store b/Getting Started/.DS_Store deleted file mode 100644 index c22d52745b68ddc8832f2eeec215ca7582a367e2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeHKL2uJA6n^fyE!BjS!zRHk64!2&f>t3ep^O7pg5UtCBuzylvUp0;pNKp-W2c8=i*Y~uhIMRY7pP>6 znr3uNF}&Kyc7eZ90bV7=PH>{q`e7kO6IgTYtT+3D`??R)#)f%h(&>n5t> zdQpwz@(s6MYMm!n^*DKz&6Yw&+AS6 zJIm#8G#d7U;plYL50;OHgMRSv!Rcz%^N#M`d;DVZF+VRfO94~Z{$jT*UcqNn)+Tis zl|`bEvr+`!7KT&|shXBqPT5Ju<(Sbsq0KhK7VyN?5f;oZ3&|+&4JuqdcKtombiJ=S~ z@xbPV7F&acPRc$$l>M@@FBBzT$M}JylL`&G(kb8+SXW@jG=0ARpZ)&*zfN*3r+`!7 zpHe_|&!V$2reyEdjmhy{8^GVg**LE?_>+Q)T*b)ctN1ot4Do;~z|dlA5D}RB5fB+% K;S~6z3j6@o&wZi* diff --git a/Getting Started/create-a-site.md b/getting-started/create-a-site.md similarity index 100% rename from Getting Started/create-a-site.md rename to getting-started/create-a-site.md diff --git a/Getting Started/create-article-cli.md b/getting-started/create-article-cli.md similarity index 100% rename from Getting Started/create-article-cli.md rename to getting-started/create-article-cli.md diff --git a/Getting Started/create-project.md b/getting-started/create-project.md similarity index 100% rename from Getting Started/create-project.md rename to getting-started/create-project.md diff --git a/Getting Started/install-cli.md b/getting-started/install-cli.md similarity index 100% rename from Getting Started/install-cli.md rename to getting-started/install-cli.md diff --git a/Getting Started/publish-article.md b/getting-started/publish-article.md similarity index 100% rename from Getting Started/publish-article.md rename to getting-started/publish-article.md diff --git a/Getting Started/what-is-curvenote.md b/getting-started/what-is-curvenote.md similarity index 100% rename from Getting Started/what-is-curvenote.md rename to getting-started/what-is-curvenote.md diff --git a/myst.yml b/myst.yml index 8bbb2ec..bb94d90 100644 --- a/myst.yml +++ b/myst.yml @@ -42,7 +42,7 @@ project: - file: solutions.md - title: Getting Started children: - - file: getting-started/What-is-curvenote.md + - file: getting-started/what-is-curvenote.md - file: getting-started/install-cli.md - file: getting-started/create-project.md - file: getting-started/create-article-cli.md @@ -64,7 +64,7 @@ project: - file: authoring/reuse-blocks.md - file: authoring/version-history.md - file: authoring/writing-markdown-myst-jupyter.md - + - title: Computational articles children: - file: computational-articles.md From 3f44043d10156fe6e11f412b59b335d49fc63992 Mon Sep 17 00:00:00 2001 From: Franklin Koch Date: Wed, 13 Aug 2025 02:36:16 -0600 Subject: [PATCH 06/26] Remove DS_Store --- .DS_Store | Bin 10244 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store deleted file mode 100644 index e3373b57ce51d6cccbfbfe3a2c55edb6720e971d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 10244 zcmeHNO>Y}T7@l=f*T!i`3aw~SrIolK6o(`&aS#_1iV#AJf@XDdin!gMFoZrBn?k z<<9%X}brG0mp!2z%k$$a18t(7{Hp%qt?*U zT^$3C0ms0C0oDf}CuKXAGcBcb;38W9$aOrH18wXB1mowjoy(b)0)6omv1pV z4aa+*>X7YR&a~8UKJegEHl8pdsTH+pfVK}_U}xk z4{`4PEr)}1CwqH;c$KyFYt`$u>$OJho6c!6?M!-;EIsaxzvA8J zNfHI~b}#rM98SAiuYZ)plU^7P#{vikL#TZHWf%{V>2Z?9gH*5`{i0T{)w^4FE-nsQ zt%Du^pmlh;<6pdgu(#tsxPN$gS+CuC>)j7N>pqD_aq@!^V<19cBjB32@5?P$w} zTg;}18FGH+d`o92f%UTySht^Pk?aj&wcHjNH*MX6zlIoF1h$?oJU2o+#Ymg#5iBL} zToWD*h1CoRu*wgnm z`>Of`+7tYA#QLg(w)P0D*l2pe+cdmz1=>jX-=2HI-$lY7zIU|aH}_ljnej&taC6k! zFJwG38pq0v{|PUznCDUrFyrJuc{J^BN>n})M!1sp$suMH z038&tms9d6|<&|Ye2G|E_sd&R=%|uB+rrb5t4BkXX&bM z;ogKE862S>X8j!7#8ckse@&QmrDWXX+Ok^5m`^e4QO?)WI9L}f#5NGDH_Rqxv|h1v zT$Sb&S0Bs58?azA%#8kbeQkmrM&&cOx9r`$(jIG8f(X~EYzZ&orQZ!N-72xkYLrQA zok|uA$|8f6x?)Cemnx3BDfc$v%-~V5165Q+@11~uP-ulDN!()&z z|3+5igWuYHoZsQ(LA{xl0>MQ-$3x2Jc--)F{M$IGyGO|b?RG9_TH* Date: Thu, 14 Aug 2025 08:46:22 -0600 Subject: [PATCH 07/26] Update getting-started/create-project.md Co-authored-by: Franklin Koch --- getting-started/create-project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-project.md b/getting-started/create-project.md index c9a4f18..40d428d 100644 --- a/getting-started/create-project.md +++ b/getting-started/create-project.md @@ -93,7 +93,7 @@ content/ You can preview your content locally by running: ```bash -curvenote preview +curvenote start ``` This launches a local development server where you can see your project as it will appear online. From cf7deb82fe9dad6089205016ec12db36bf8c78d2 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:48:18 -0600 Subject: [PATCH 08/26] Update getting-started/create-article-cli.md Co-authored-by: Franklin Koch --- getting-started/create-article-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index 6fa5cc6..8c0d98f 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -42,7 +42,7 @@ Open the new file in your preferred text editor: code content/my-first-article.md ``` -You can write in **Markdown**, **MyST**, or embed Jupyter code blocks if your project supports it. +You can write in **MyST Markdown** or use **Jupyter Notebooks**. Example content: From 4a3f1a3f02da00fcf009280bb715dea3f3cff096 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:48:51 -0600 Subject: [PATCH 09/26] Update getting-started/create-article-cli.md Co-authored-by: Franklin Koch --- getting-started/create-article-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index 8c0d98f..fb37b71 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -60,7 +60,7 @@ This is my first article written in Curvenote! 🎉 ## My First Figure -```{figure} assets/fig1.png +```{figure} ../assets/fig1.png :alt: Example figure :width: 60% ``` From e849f4acbab1c8a8d8f8464b390ebedfe338f75b Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:49:44 -0600 Subject: [PATCH 10/26] Update getting-started/create-article-cli.md Co-authored-by: Franklin Koch --- getting-started/create-article-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index fb37b71..7dfdfa9 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -72,7 +72,7 @@ Figure caption goes here. See your changes instantly by running: ```bash -curvenote preview +curvenote start ``` This opens a local preview of your site in your browser so you can check formatting, figures, and links. From 3ac740f172a59ce9196f4869dac23ec19ec7111f Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:51:03 -0600 Subject: [PATCH 11/26] Update getting-started/create-a-site.md Co-authored-by: Franklin Koch --- getting-started/create-a-site.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index 5e3a97f..5439d46 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -7,7 +7,9 @@ short_title: Create a Site # Create a Site -:::{tip} ObjectiveCreate a publishing destination for your articles, lab notebooks, or group collections. ::: +:::{tip} Objective +Create a publishing destination for your articles, lab notebooks, or group collections. +::: ## Quick Checklist From 0c2c3c2c36fdae79248934ed62ee89a6b641c99f Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:51:22 -0600 Subject: [PATCH 12/26] Update getting-started/create-a-site.md Co-authored-by: Franklin Koch --- getting-started/create-a-site.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index 5439d46..501d3c1 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -14,7 +14,7 @@ Create a publishing destination for your articles, lab notebooks, or group colle ## Quick Checklist - Have a Curvenote account & CLI installed -- Access or create a site (web admin) +- Access to create a site (web admin) - Configure your project (curvenote.yml) - Organize local content (if using Git/GitHub) - Add metadata to each file From 889fc1b4b34c1a3af99119b90ae65c82f4d3e89f Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:54:36 -0600 Subject: [PATCH 13/26] Update getting-started/create-a-site.md Co-authored-by: Franklin Koch --- getting-started/create-a-site.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index 501d3c1..f740bf3 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -149,7 +149,7 @@ This will run structural and metadata checks and highlight any issues. Publishing makes submitted content live on the site: ```bash -curvenote submission publish +curvenote submission publish ``` Only site admins can publish. Once published: From 6c356992097471cee356e0d8c6350f13b0a2d99e Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:55:04 -0600 Subject: [PATCH 14/26] Update getting-started/create-a-site.md Co-authored-by: Franklin Koch --- getting-started/create-a-site.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index f740bf3..c680b89 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -115,7 +115,7 @@ Metadata enables automated checks, collection assignment, and proper formatting From your local project, run: ```bash -curvenote submit +curvenote submit ``` You’ll be prompted to: From 2602d7d3d1efd94a16c5febaf0d602f778250d96 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 08:55:48 -0600 Subject: [PATCH 15/26] Update getting-started/create-a-site.md Co-authored-by: Franklin Koch --- getting-started/create-a-site.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index c680b89..8fa0dd4 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -160,5 +160,5 @@ Only site admins can publish. Once published: ## After Publishing - Share links to your articles or site homepage -- Updates and re-publish (each update is tracked) +- Update and re-publish (each update is tracked) - Embed individual figures, notebooks, or methods in other sites and tools. From 1e2f50096e6498d05a0b0eef4bcc3c2eb19478a8 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Thu, 14 Aug 2025 21:52:39 -0600 Subject: [PATCH 16/26] docs: improve getting-started guides with flexible structure, accurate CLI steps, and clearer project definition --- cli/authentication.md | 110 ++++++++++++--------------- getting-started/create-a-site.md | 63 +++++++-------- getting-started/create-project.md | 88 ++++++++++----------- getting-started/install-cli.md | 59 ++++++-------- getting-started/what-is-curvenote.md | 18 ++--- 5 files changed, 145 insertions(+), 193 deletions(-) diff --git a/cli/authentication.md b/cli/authentication.md index 4a9858e..9f0d4f8 100644 --- a/cli/authentication.md +++ b/cli/authentication.md @@ -1,89 +1,73 @@ --- title: Authentication +short_title: Authentication --- -Most translation and export functionality is local and **does not** require you to be logged into Curvenote. Additionally, the API for any public content on Curvenote does not require you to be authenticated. However, if you want to sync content from your _private_ Curvenote projects to a local folder, modify any online projects, or deploy a website you will need to be authenticated. - -The Curvenote CLI works on an API token that can be generated from your personal settings on [curvenote.com](https://curvenote.com). - -## Creating an API Token +**Goal:** +Sign in to the Curvenote CLI using an API token so you can work with private projects, sync content, and publish. +::: -API Tokens allow you to access your Curvenote content programmatically. +## When You Need to Authenticate +- Accessing **private projects** from Curvenote +- Modifying or syncing content online +- Publishing content to a site +- Running CI/CD or automation scripts -🛠️ You can create an API token by clicking [here](https://curvenote.com/profile?settings=true&tab=profile-api) if you are signed in or navigating to your **Personal Settings**, which are available under your avatar in the top right. +Most translation/export of **public content** does not require authentication. -```{figure} images/settings-api-token.png -:name: FdFCmj6QcJ -:align: center -:width: 70% +## 1. Generate an API Token +1. Sign in to [Curvenote](https://curvenote.com/). +2. Go to **Personal Settings** → **API Access** or [click here](https://curvenote.com/profile?settings=true&tab=profile-api). +3. Click **Generate New Token**. +4. Copy the token — you won’t be able to see it again. -Access the API Token by navigating to your **Personal Settings** by clicking on your avatar in the top right. +## 2. Store the Token Locally +Run: +```bash +curvenote token set ``` +Paste the API token when prompted. -🛠️ Click on the **Generate New Token**, and give you token a description that you can recognize lated if you need to revoke it. You will be shown a screen that allows you to copy the API token for the next step. +## 3. Store the Token as an Environment Variable -```{figure} images/settings-api-copy-token.png -:name: rm1dO7qLHx -:align: center -:width: 70% +Useful for CI/CD or servers: -Ensure that you copy your token for the next step. You will not be able to access this token again. +```bash +export CURVENOTE_TOKEN="API_TOKEN" ``` +The environment variable takes priority over stored tokens. -🛠️ Copy the API Token. You will not be able to see this token again, so be sure to copy it! - -## Sign In to Curvenote using the CLI +## 4. Switch Accounts -🛠️ Sign into the Curvenote CLI using the command: +If you have multiple accounts: -```python -curvenote token set +```bash +curvenote token select ``` -You will be asked for an API Token which you copied from your API Access settings in Curvenote (see above). The command will store a local config file that has your API token to be used for future calls to the library. - -### Validate you are signed in - -🛠️ You can validate that you are signed in using the command: - -```shell +## 5. Check Authentication Status +```bash curvenote auth list ``` +Shows your current account or indicates if not authenticated. -This will print your username and email or tell you that you are not authenticated. -This command will also list any other accounts that you can login as. - -### Changing Profiles - -If you have multiple Curvenote accounts, for example, as a bot for a submission system, you can switch profiles using: - -```shell -curvenote token select +## 6. Sign Out +```bash +curvenote token delete ``` -This will bring up a prompt to select which account you should use for the Curvenote API. - -### Authenticating on a Server - -You can also override the config path by having a `CURVENOTE_TOKEN` in your environment, this is helpful when using the Curvenote CLI from a continuous integration system or on a server. - -```shell -export CURVENOTE_TOKEN="API_TOKEN" +Removes the stored token. If using an environment variable, unset it: +```bash +unset CURVENOTE_TOKEN ``` -:::{warning} `CURVENOTE_TOKEN` environment variable takes priority -If the environment variable is present, it will have precedence over any token you have set previously. -The CLI will notify you through a log message about which token is being used. -::: - -Alternatively, you can use the `curvenote token set $ENV_VAR` to set the token programmatically; we recommend not to paste your token into the command line directly as that will create an entry in your terminal history. - -## Sign Out of Curvenote - -To sign out of the Curvenote CLI, you can call: - -```shell -curvenote token delete -``` +💡 **Tips:** +- You only need to authenticate if working with private projects or publishing to a site. +- Store the API token in an environment variable (`CURVENOTE_TOKEN`) for CI/CD. +- Use `curvenote token select` to switch between accounts. -This will remove the local config file with the API token in it. Note, if you have signed into the CLI using the environment variable, you can unset that using `unset CURVENOTE_TOKEN`. To confirm that you are logged out you can run the command `curvenote auth list` as before, and it should inform you that you are not authenticated. +## Related Guides +- [Install & Authenticate CLI (Tutorial)](install-cli.md) +- [Push, Submit, and Publish Content](push-submit-publish.md) +- [Set Up a Site for Publishing](setup-site.md) +- [Continuous Integration with Curvenote CLI](ci-cli.md) \ No newline at end of file diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index 8fa0dd4..4d00a59 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -7,7 +7,7 @@ short_title: Create a Site # Create a Site -:::{tip} Objective +**Goal** Create a publishing destination for your articles, lab notebooks, or group collections. ::: @@ -26,39 +26,20 @@ Create a publishing destination for your articles, lab notebooks, or group colle ## Workflow at a Glance ```mermaid -graph TD - A[1. Create Site
web admin] --> B[2. Set Landing Page] - B --> C[3. Organize Content
optional for local/Git] - C --> D[4. Add Metadata] - D --> E[5. Submit Content] - E --> F[6. Push Changes
optional] - F --> G[7. Run Checks
optional] - G --> H[8. Publish
admin only] - H --> I[🎉 Site Live!] - - style A fill:#e1f5fe - style I fill:#c8e6c9 +flowchart TD + A[1. Create Site (web admin)] --> B[2. Set Landing Page] + B --> C[3. Organize Content (optional)] + C --> D[4. Add Metadata] + D --> E[5. Submit Content] + E --> F[6. Push Changes (optional)] + F --> G[7. Run Checks (optional)] + G --> H[8. Publish (admin only)] + H --> I[Site Live!] + + style A fill:#e1f5fe + style I fill:#c8e6c9 ``` -**Text Version:** - -``` -[1] Create Site (web admin) - ↓ -[2] Set Landing Page - ↓ -[3] Organize Content (optional for local/Git) - ↓ -[4] Add Metadata - ↓ -[5] Submit Content → [6] Push Changes (optional) - ↓ -[7] Run Checks (optional) - ↓ -[8] Publish (admin only) - ↓ - 🎉 Site Live! -``` ## Before You Begin :::{important} Make sure you have: @@ -108,7 +89,7 @@ kind: article --- ``` -Metadata enables automated checks, collection assignment, and proper formatting +Metadata enables automated checks, collection assignment, and proper formatting. See (metadata.md) for more details. ### 5. Submit Content to a Site and Collection @@ -134,15 +115,15 @@ curvenote push This allows collaborators to preview your work, but does not make it publicly visible. ### 7. Run Checks (Optional but Recommended) - +Run structural and metadata checks to catch errors before publishing: ```bash -curvenote check +curvenote check ``` -This will run structural and metadata checks and highlight any issues. +Include the site (venue) ID so the check runs in the correct publishing context. This ensures the content is validated against the specific site’s configuration and collections. -> 💡 **Tip:** For more details on how to run a structural check, visit this page (link) +> 💡 **Tip:** For step-by-step instructions on running a structural check and resolving any issues, see [Integrity Checks](https://curvenote.com/docs/publish/integrity-checks) ### 8. Publish Content (Admin Action) @@ -162,3 +143,11 @@ Only site admins can publish. Once published: - Share links to your articles or site homepage - Update and re-publish (each update is tracked) - Embed individual figures, notebooks, or methods in other sites and tools. + +## Related Guides + +- [Install & Authenticate the Curvenote CLI](install-cli) +- [Add Metadata to Your Content](/metadata) +- [Push, Submit, and Publish Content](publish-article) +- [Run Integrity Checks](https://curvenote.com/docs/publish/integrity-checks) +- [Manage Collections in a Site](https://curvenote.com/docs/publish/collections) diff --git a/getting-started/create-project.md b/getting-started/create-project.md index 40d428d..d8f322e 100644 --- a/getting-started/create-project.md +++ b/getting-started/create-project.md @@ -8,18 +8,25 @@ short_title: Create Project **Goal:** Create and organize your first Curvenote project so you can start writing and publishing content. - ## 1. What’s a Project in Curvenote? -A **project** is the home for your articles, figures, datasets, and other content. -It also stores your site configuration so you can publish to the web. +A **project** is the container for everything you want to publish in Curvenote — including articles, figures, datasets, media, and the configuration that controls how they appear online. + +A project can be: +- **A single article** — for example, a preprint, report, or tutorial. +- **A multi-article collection** — such as a lab website, conference proceedings, or journal issue. +- **A research output with multiple parts** — combining text, interactive figures, and linked data/code. + +The `curvenote.yml` file defines the project’s metadata, structure, and publishing settings, whether your project is just one file or a large collection. + -Projects contain: +Projects typically include: -- **Content folder** (`content/`) for articles, sections, and figures. -- **Configuration file** (`curvenote.yml`) for site and article settings. -- **Assets folder** for images, datasets, and other media. +- **Configuration file** (`curvenote.yml`) — **Required.** Defines site settings, article metadata, and publishing options. +- **Content files** — Any `.md`, `.ipynb`, or `.tex` files containing your articles, sections, and figures. These can be organized in any folder structure. +- **Supporting files** — Images, datasets, scripts, or other media used in your articles. These can be stored anywhere in the project. +There is no required folder naming convention; organize files and directories in the way that best suits your workflow. ## 2. Create a New Project @@ -27,26 +34,20 @@ Projects contain: From your terminal: ```bash -curvenote init my-first-project +curvenote init ``` +When you run this command, you’ll be prompted to choose how to initialize the project: -You’ll be prompted to: +## 1. Import from Curvenote — Pulls content from the legacy web editor at curvenote.com. +*Note: This workflow is not recommended for new projects and may be removed in future versions.* -1. **Name your project** - Example: `My Lab Website` or `My Article` -2. **Add an optional description** -3. Confirm your configuration. +## 2. Use the content in this folder — Treats the current folder as a Curvenote project using the existing files inside it. -This creates a folder with the following structure: +- This option is only available if the folder already contains content (e.g., `.md`, .`ipynb`, .`tex` files) and you are starting from that folder. -``` -my-first-project/ -├── content/ -│ └── index.md -├── curvenote.yml -└── README.md -``` +For new projects, we recommend starting in a folder where you’ve already added your initial article or content files. +Then, run `curvenote init` from that folder to create the required curvenote.yml configuration file and begin organizing your content. ## 3. Navigate and Explore @@ -56,38 +57,32 @@ Move into your new project folder: cd my-first-project ``` -Open `content/index.md` in your editor — this is your first article. -You can rename it, add more `.md` or `.myst.md` files, and create subfolders for sections. - +Open `/index.md` in your editor — this is your first article. +You can rename it, add more `.md` or `.myst.md`, `ipynb` or `.tex` files, and organize them in folders that make sense for your project. ## 4. Organize Your Content -Best practices: +Best practices (adapt as needed for your workflow): - **One article per file** for clarity. - Group related articles into folders (e.g., `/methods`, `/results`). -- Keep images and figures in an `/assets` folder. +- Store images and figures wherever is most convenient — for example, alongside the articles that reference them, or in a dedicated folder like `assets/` or `media/`. - Use clear, short file names (avoid spaces). Example: - -``` -content/ -├── introduction.md -├── methods/ -│ ├── data-collection.md -│ └── analysis.md -├── results/ -│ ├── experiment-1.md -│ └── experiment-2.md -└── assets/ - ├── fig1.png - └── dataset.csv +```arduino +methods/ +├── data-collection.md +└── analysis.md +results/ +├── experiment-1.md +└── experiment-2.md +assets/ +├── shared-logo.png +└── dataset.csv ``` - - ## 5. Check Your Setup You can preview your content locally by running: @@ -98,17 +93,14 @@ curvenote start This launches a local development server where you can see your project as it will appear online. - - - ## Next Steps Now that you have a project: -1. [Write Your First Article →](../how-to/create-article-cli.md) -2. [Publish & Share →](../how-to/publish-article.md) -3. [Set Up a Site →](../getting-started/set-up-site.md) +1. [Write Your First Article](create-article-cli.md) +2. [Publish & Share](publish-article.md) +3. [Set Up a Site →](create-a-site.md) --- -**Tip:** You can connect your project to GitHub for version control. See [Connect to GitHub](../integrations/github.md). \ No newline at end of file +💡 **Tip:** You can connect your project to GitHub for version control. See [Connect to GitHub](../integrations/github.md). \ No newline at end of file diff --git a/getting-started/install-cli.md b/getting-started/install-cli.md index d34be54..9eb9fca 100644 --- a/getting-started/install-cli.md +++ b/getting-started/install-cli.md @@ -5,15 +5,16 @@ short_title: Install CLI # Install & Authenticate the Curvenote CLI -**Goal:** Install the Curvenote command-line tool, log in, and ensure you're ready to create and publish content. +**Goal:** +Install the Curvenote command-line tool, log in, and ensure you're ready to create and publish content. -## Prerequisites +## Before You Start -Before installing the CLI, make sure you have: +Make sure you have: -- **Node.js v18 or later** (comes with `npm`) +**Node.js v18 or later** (comes with `npm`) - Check your version: ```bash node --version @@ -23,8 +24,6 @@ Before installing the CLI, make sure you have: conda install -c conda-forge nodejs ``` - - ## 1. Install the CLI Open your terminal and run: @@ -33,48 +32,38 @@ Open your terminal and run: npm install -g curvenote ``` -After installation, verify the CLI is installed: +Verify installation: ```bash curvenote --version ``` -You should see a version number (e.g., `0.1.2`). -If you see an error, check your Node.js and `npm` setup. +You should see a version number. If you see an error, check your Node.js and `npm` setup. ## 2. Authenticate with Curvenote -Run the login command: -```bash -curvenote login -``` -1. Your browser will open to the Curvenote sign-in page. -2. Sign in with your Curvenote account. - -3. Once you return to the terminal, you should see a confirmation message like: -``` -Logged in as -``` +You’ll need an API token if working with private projects or publishing to a site. -If you use multiple accounts, you can switch by running: +1. In your Curvenote Personal Settings, generate a new API token. +2. In your terminal, run: ```bash -curvenote token select +curvenote token set ``` +3. Paste the API tocken when prompted. + +For more options, see the full [Authentication Reference](../cli/authentication.md). + ## 3. Verify Your Setup -To confirm you’re ready to go: +Run: ```bash -curvenote whoami +curvenote token check ``` - -If it returns your username, your CLI is authenticated and ready. - +If it returns your username, your CLI is ready. ## Next Steps -Now that you’ve installed and authenticated the CLI, you can: - -1. [Create Your First Project →](../getting-started/organize-content.md) -2. [Write Your First Article →](../how-to/create-article-cli.md) -3. [Publish & Share →](../how-to/publish-article.md) - ---- +1. [Create Your First Project](create-project.md) +2. [Write Your First Article from the CLI](create-article-cli.md) +3. [Set Up a Site for Publishing](create-a-site.md) +4. [Push, Submit, and Publish Content](push-submit-publish.md) -**Tip:** The Curvenote CLI is open source—[view it on GitHub](https://github.com/curvenote/curvenote). +💡 **Tip:** The Curvenote CLI is open source—[view it on GitHub](https://github.com/curvenote/curvenote). +::: diff --git a/getting-started/what-is-curvenote.md b/getting-started/what-is-curvenote.md index ccbbbe1..926fe5e 100644 --- a/getting-started/what-is-curvenote.md +++ b/getting-started/what-is-curvenote.md @@ -18,7 +18,6 @@ Most research outputs today are frozen in time—locked into PDFs and detached f - **Web-first publishing** for better discoverability - **One-click exports** to Typst or PDF when needed - Work in your browser or use the Curvenote CLI: - Write in **Markdown, Jupyter**, or the Curvenote editor @@ -29,14 +28,13 @@ Work in your browser or use the Curvenote CLI: --- -## Publishing as part of your workflow -Publishing with Curvenote is fast and flexible. You can publish: +## The platform for modern research + +Curvenote modernizes how scientific research is written, managed, and published. With Curvenote, you can publish: - Single articles - Multi-article collections (lab sites, conference proceedings, documentation) -- Research outputs with **interactive figures, notebooks, and citations** - -Everything you publish stays editable and updateable—no reformatting required. +- Research outputs with **interactive figures, notebooks, and citations** ## Built for research teams @@ -50,10 +48,10 @@ Curvenote supports: ## Why it matters -Scientific knowledge should be **open, versioned, and reusable**. Curvenote provides the infrastructure for **living research outputs**—helping you move faster, stay organized, and share work in ways that are valuable to both humans and machines. +Scientific knowledge should be **open, versioned, and reusable**. Curvenote provides the infrastructure for **living research outputs** that evolve with your work. Our platform organizes research into modular, discoverable components that work across any project, enabling collaborative web-first workflows that connect with your existing tech stack. ## Next steps -1. [Install the CLI](install-cli.md) -2. [Set up your first publishing site](set-up-site.md) -3. [Write and publish your first article](create-article-cli.md) \ No newline at end of file +1. [Install the CLI](getting-started/install-cli.md) +2. [Set up your first publishing site](getting-started/create-a-site.md) +3. [Write and publish your first article](getting-started/create-article-cli.md) \ No newline at end of file From 930bfefb294f7f420fcbdce44b08368f27caa468 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 12:06:31 -0600 Subject: [PATCH 17/26] Update authentication.md --- cli/authentication.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/cli/authentication.md b/cli/authentication.md index 9f0d4f8..d63452e 100644 --- a/cli/authentication.md +++ b/cli/authentication.md @@ -5,7 +5,6 @@ short_title: Authentication **Goal:** Sign in to the Curvenote CLI using an API token so you can work with private projects, sync content, and publish. -::: ## When You Need to Authenticate - Accessing **private projects** from Curvenote @@ -70,4 +69,4 @@ unset CURVENOTE_TOKEN - [Install & Authenticate CLI (Tutorial)](install-cli.md) - [Push, Submit, and Publish Content](push-submit-publish.md) - [Set Up a Site for Publishing](setup-site.md) -- [Continuous Integration with Curvenote CLI](ci-cli.md) \ No newline at end of file +- [Continuous Integration with Curvenote CLI](ci-cli.md) From 6aee4939b04b90f12351c785dd9c1ded03e34901 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 13:46:31 -0600 Subject: [PATCH 18/26] Update create-article-cli.md --- getting-started/create-article-cli.md | 29 ++++++++++++--------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index 7dfdfa9..d06b7bd 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -12,26 +12,25 @@ short_title: Write Article ## 1. Create a New Article -From inside your project folder, run: +To create a new article, simply add a new Markdown file to your project’s content/ directory using your preferred text editor or IDE. +For example, create a file called `my-first-article.md`: ```bash -curvenote create article my-first-article -``` - -This will: - -- Create a new Markdown file in your `content/` directory. -- Add default frontmatter (metadata) like `title` and `date`. -- Link the article into your site navigation if your `curvenote.yml` is set up. - -Example folder after running the command: - -``` content/ ├── index.md └── my-first-article.md ``` +Each article should start with YAML frontmatter containing at least a title field. For example: +```bash +--- +title: My First Article +date: 2025-08-15 +--- +``` +Once created, you can add the new article to your site navigation by editing `curvenote.yml` and linking to the file. + +💡 **Tip**: If your project is already linked to a Curvenote site, you can use curvenote push to sync changes for review or curvenote submit to send it to a collection. ## 2. Open and Edit Your Article @@ -85,10 +84,10 @@ Best practices for keeping articles manageable: - Use short, descriptive file names. - Group related content into folders (e.g., `methods/`, `results/`). +- Store images and figures wherever is most convenient — for example, alongside the articles that reference them, or in a dedicated folder like `assets/` or `media/`. - Keep figures, datasets, and large media files in an `assets/` folder. - ## Next Steps Once your article looks good, you can: @@ -97,6 +96,4 @@ Once your article looks good, you can: 2. [Add Figures, Images, and Media →](../authoring/add-figures-media.md) 3. [Link Data and Code →](../authoring/link-data-code.md) ---- -**Tip:** Curvenote supports reusable content blocks, so you can keep figures, citations, or sections consistent across multiple articles. From 400003635c269a43c9ad9bf759c300bf37668dce Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 13:51:11 -0600 Subject: [PATCH 19/26] Update create-article-cli.md --- getting-started/create-article-cli.md | 26 ++------------------------ 1 file changed, 2 insertions(+), 24 deletions(-) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index d06b7bd..17ad820 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -35,36 +35,14 @@ Once created, you can add the new article to your site navigation by editing `cu ## 2. Open and Edit Your Article -Open the new file in your preferred text editor: +Open the new file in your preferred text editor (for example, VS Code, Sublime Text, or another editor you use). +If you use Visual Studio Code, you can open the file directly from your terminal: ```bash code content/my-first-article.md ``` - You can write in **MyST Markdown** or use **Jupyter Notebooks**. -Example content: - -```markdown ---- -title: My First Curvenote Article -authors: - - name: Jane Doe - orcid: 0000-0001-2345-6789 ---- - -# Introduction - -This is my first article written in Curvenote! 🎉 - -## My First Figure - -```{figure} ../assets/fig1.png -:alt: Example figure -:width: 60% -``` -Figure caption goes here. - ## 3. Preview Locally From e2f0b0377dafda9a3e0ead9169c12347f66619dc Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 13:59:24 -0600 Subject: [PATCH 20/26] Update create-article-cli.md --- getting-started/create-article-cli.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index 17ad820..29a76cb 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -55,15 +55,9 @@ curvenote start This opens a local preview of your site in your browser so you can check formatting, figures, and links. - ## 4. Organize Your Articles -Best practices for keeping articles manageable: - -- Use short, descriptive file names. -- Group related content into folders (e.g., `methods/`, `results/`). -- Store images and figures wherever is most convenient — for example, alongside the articles that reference them, or in a dedicated folder like `assets/` or `media/`. -- Keep figures, datasets, and large media files in an `assets/` folder. +For best practices on organizing content, see [Organize Articles and Sections](.organize-content.md) ## Next Steps From a3a999ad361971d6ffa71c84b9ff919830444bc1 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 14:39:53 -0600 Subject: [PATCH 21/26] Update create-a-site.md --- getting-started/create-a-site.md | 166 ++++++------------------------- 1 file changed, 32 insertions(+), 134 deletions(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index 4d00a59..fa92818 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -1,153 +1,51 @@ --- -title: How to Set Up a Publishing Site in Curvenote +title: Create a Site in Curvenote short_title: Create a Site --- - - # Create a Site -**Goal** -Create a publishing destination for your articles, lab notebooks, or group collections. -::: - -## Quick Checklist - -- Have a Curvenote account & CLI installed -- Access to create a site (web admin) -- Configure your project (curvenote.yml) -- Organize local content (if using Git/GitHub) -- Add metadata to each file -- Submit content to a site & collection -- Push changes for internal review (optional) -- Run checks before publishing (optional) -- Publish (admin only) - -## Workflow at a Glance - -```mermaid -flowchart TD - A[1. Create Site (web admin)] --> B[2. Set Landing Page] - B --> C[3. Organize Content (optional)] - C --> D[4. Add Metadata] - D --> E[5. Submit Content] - E --> F[6. Push Changes (optional)] - F --> G[7. Run Checks (optional)] - G --> H[8. Publish (admin only)] - H --> I[Site Live!] - - style A fill:#e1f5fe - style I fill:#c8e6c9 -``` - - ## Before You Begin -:::{important} Make sure you have: - -- A Curvenote account and Curvenote CLI installed -- Access to an existing site (or permission to create one via the web admin interface) -- A configured project (curvenote.yml) if publishing from GitHub or locally -::: - - -### 1. Create a Site (via Web Admin) - -Currently, new sites must be created through the web admin interface. - -- Choose a title and subdomain (e.g., `my-lab.curve.space`) -- Set the site visibility (public or private) -- Define the organization or group that owns the site - -_Coming Soon: Site creation directly from the CLI._ - -### 2. Set a Landing Page or Featured Work - -Once the site exists, an admin can define a “landing page” — the main entry point for visitors. - -- Recommended: Set this via the web admin interface -- CLI support available for some workflows - -### 3. Organize Your Content (Optional, CLI or Git-based Workflows) - -If you are managing content locally (e.g., in GitHub), organize your files into logical directories: - -- **Full Research Articles:** `articles/` -- **Figures/Methods:** `components/` -- **Landing page:** `index.md` +**Objective:** +Create a new publishing destination for your articles, lab notebooks, or group collections. -For sites with community submissions, content organization happens after submission. -### 4. Add Metadata +## Before You Start +Make sure you have: +- A Curvenote account and [Curvenote CLI installed](install-cli.md) +- Admin permissions to create a site in the [web admin interface](https://curvenote.com) +- A title and subdomain in mind for your site -Each content file should have frontmatter with key details: - -```yaml ---- -title: 'An Advanced Microscopy Study' -authors: - - name: Dr. Lee -kind: article --- -``` - -Metadata enables automated checks, collection assignment, and proper formatting. See (metadata.md) for more details. - -### 5. Submit Content to a Site and Collection - -From your local project, run: - -```bash -curvenote submit -``` - -You’ll be prompted to: - -- Select an existing site -- Choose a collection (e.g., "Lab Articles") - -This prepares your content for publishing and notifies site administrators. - -### 6. Push Changes (Optional: Internal Review) -```bash -curvenote push -``` +## Steps to Create a Site -This allows collaborators to preview your work, but does not make it publicly visible. +### 1. Create the Site in Web Admin +Currently, site creation is only available via the web admin interface: +1. Sign in to [curvenote.com](https://curvenote.com) +2. Choose **Create Site** +3. Set: + - **Title** (e.g., “My Research Lab”) + - **Subdomain** (e.g., `my-lab.curve.space`) + - **Visibility** (public or private) + - **Owning Organization** or group -### 7. Run Checks (Optional but Recommended) -Run structural and metadata checks to catch errors before publishing: +_Coming Soon: CLI-based site creation._ -```bash -curvenote check -``` +### 2. Set the Landing Page +The landing page is the main entry point for visitors to your site: +- Choose a featured article, collection, or custom page +- Recommended: Set this in the web admin interface -Include the site (venue) ID so the check runs in the correct publishing context. This ensures the content is validated against the specific site’s configuration and collections. - -> 💡 **Tip:** For step-by-step instructions on running a structural check and resolving any issues, see [Integrity Checks](https://curvenote.com/docs/publish/integrity-checks) - -### 8. Publish Content (Admin Action) - -Publishing makes submitted content live on the site: - -```bash -curvenote submission publish -``` - -Only site admins can publish. Once published: - -- Content appears on the site -- DOI, metadata, and links are activated +--- -## After Publishing +## After Creating the Site +- Share the subdomain with collaborators +- Add content by following [Submit & Publish Content](submit-publish.md) +- Customize the landing page content over time -- Share links to your articles or site homepage -- Update and re-publish (each update is tracked) -- Embed individual figures, notebooks, or methods in other sites and tools. +--- ## Related Guides - -- [Install & Authenticate the Curvenote CLI](install-cli) -- [Add Metadata to Your Content](/metadata) -- [Push, Submit, and Publish Content](publish-article) -- [Run Integrity Checks](https://curvenote.com/docs/publish/integrity-checks) -- [Manage Collections in a Site](https://curvenote.com/docs/publish/collections) +- [Install & Authenticate CLI](install-cli.md) +- [Set Up a Site for Publishing](metadata.md) +- [Submit & Publish Content](submit-publish.md) From f0a3d8bf55c7464f32bc348aa32eef7124020869 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 15:22:57 -0600 Subject: [PATCH 22/26] Update create-a-site.md Updated to our new request site form and tweaked language to align with "manage site" --- getting-started/create-a-site.md | 81 +++++++++++++++----------------- 1 file changed, 39 insertions(+), 42 deletions(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index fa92818..ffc476b 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -1,51 +1,48 @@ --- -title: Create a Site in Curvenote +title: Create a Site short_title: Create a Site --- -# Create a Site - **Objective:** -Create a new publishing destination for your articles, lab notebooks, or group collections. - +Request a Curvenote site and manage landing and submission content. ## Before You Start -Make sure you have: -- A Curvenote account and [Curvenote CLI installed](install-cli.md) -- Admin permissions to create a site in the [web admin interface](https://curvenote.com) -- A title and subdomain in mind for your site - +- Curvenote account + CLI installed +- Only Curvenote staff can create sites (use onboarding form) + +## Steps + +### 1. Request a Site +- Fill out the [Site Setup Request Form](https://forms.gle/Y8ppqCpPFKPH5GFr7) +- Curvenote will set up: + - Title & subdomain (`my-lab.curve.space`) + - Public/private visibility + - Initial landing content +- Receive confirmation email when live + +### 2. Manage Landing Content +- Landing page = main entry point for visitors +- Update via **web admin** +- Feature articles, collections, or projects +- Configure your hero banner to highlight key work — see [Hero Unit & Background Images](planning.md) +- More planning tips in [Planning Your Site](planning.md) + +### 3. Manage Submissions +- Contributors submit via: + ```bash + curvenote submit ``` + +- Review & publish as admin +- See [Publish & Share] (publish-article.md) + +## 4.Repo Setup Pattern (Git/GitHub) +- `content/` for articles +- `assets/` for figures/images +- Collections in `curvenote.yml` +- See [Organize Content into Sections](organize-content.md) --- - -## Steps to Create a Site - -### 1. Create the Site in Web Admin -Currently, site creation is only available via the web admin interface: -1. Sign in to [curvenote.com](https://curvenote.com) -2. Choose **Create Site** -3. Set: - - **Title** (e.g., “My Research Lab”) - - **Subdomain** (e.g., `my-lab.curve.space`) - - **Visibility** (public or private) - - **Owning Organization** or group - -_Coming Soon: CLI-based site creation._ - -### 2. Set the Landing Page -The landing page is the main entry point for visitors to your site: -- Choose a featured article, collection, or custom page -- Recommended: Set this in the web admin interface - ---- - -## After Creating the Site -- Share the subdomain with collaborators -- Add content by following [Submit & Publish Content](submit-publish.md) -- Customize the landing page content over time - ---- - ## Related Guides -- [Install & Authenticate CLI](install-cli.md) -- [Set Up a Site for Publishing](metadata.md) -- [Submit & Publish Content](submit-publish.md) +- [Hero Unit & Background Images](planning.md) +- [Planning Your Site](planning.md) +- [Publish & Share](publish-article.md) +- [Organize Content into Sections](organize-content.md) From fa49d8f9e5780f8436732c8b8f4827c0d3284f27 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 15:55:26 -0600 Subject: [PATCH 23/26] Update publish-article.md Replaced incorrect command Clarified article change process --- getting-started/publish-article.md | 63 +++++++++++++----------------- 1 file changed, 28 insertions(+), 35 deletions(-) diff --git a/getting-started/publish-article.md b/getting-started/publish-article.md index a4daa82..c35c039 100644 --- a/getting-started/publish-article.md +++ b/getting-started/publish-article.md @@ -8,62 +8,55 @@ short_title: Publish & Share **Goal:** Publish your article or site so it’s live on the web. +--- - -## 1. Make Sure Your Project Is Ready - -Before publishing, confirm that your project has: - +## Before You Publish +Check that your project has: - At least one article with content. - A valid `curvenote.yml` configuration file. -- Any required assets (figures, datasets, notebooks) included in the project. +- All required assets (figures, datasets, notebooks) included. -If you’re not sure your site is configured, see: -[Set Up a Site →](../getting-started/set-up-site.md) +If you’re not sure your site is configured, see [Set Up a Site](set-up-site.md) +--- +## Choose How You Want to Publish -## 2. Publish from the CLI +**Publish directly to the web (public)** -Run the publish command from your project folder: +This puts your project live on the `.curve.space` domain you set in `site.domains` ```bash -curvenote publish +curvenote deploy ``` -You’ll see output confirming which articles or collections are being published and the URL where your content will appear. - - - -## 3. View Your Live Site - -Once publishing finishes, the CLI will display a URL to your live site. -Open it in your browser to verify: - -- Formatting and layout look correct. -- Figures, tables, and media load properly. -- Links and citations work as expected. - - - -## 4. Update Published Content - -If you make changes to your articles, simply run: +**Submit to a site (for review or staged publishing)** +Send your project to a site (e.g., a lab site or journal). Only site admins can make it public. ```bash -curvenote publish +curvenote submit ``` -Curvenote will update the existing content without requiring you to start over. +If you have admin rights and want to publish from the CLI: +```bash +curvenote submission publish +``` +## See the Result +- **Deploy:** The CLI will show your live `.curve.space` URL. +- **Submit:** Your submission appears in the site’s admin area. + If published, the site will provide the public URL. +## Update Content +- If you deployed: Run `curvenote deploy` again to replace the live version. +- If you submitted: Run `curvenote submit ` to create a new submission version, then publish (via admin UI or `curvenote submission publish `). ## Next Steps -- [Add Figures, Images, and Media →](../authoring/add-figures-media.md) -- [Link Data and Code →](../authoring/link-data-code.md) -- [Export to PDF/Typst →](../tutorials/export-pdf.md) +- [Add Figures, Images, and Media →](add-figures-media.md) +- [Link Data and Code →](link-data-code.md) +- [Export to PDF/Typst →](export-pdf.md) --- -**Tip:** Published content is “living” in Curvenote — you can make edits anytime, and your audience will always see the latest version. \ No newline at end of file +**Tip:** Published content is “living” in Curvenote — you can make edits anytime, and your audience will always see the latest version. From 582edb4f85d1545d0e61692c9f8fc15d8a1e9153 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 16:02:05 -0600 Subject: [PATCH 24/26] Update create-a-site.md --- getting-started/create-a-site.md | 42 +++++++++----------------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index ffc476b..ac369c1 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -4,42 +4,24 @@ short_title: Create a Site --- **Objective:** -Request a Curvenote site and manage landing and submission content. +Request a Curvenote site so you can publish and share your work online. ## Before You Start -- Curvenote account + CLI installed -- Only Curvenote staff can create sites (use onboarding form) +- Curvenote account + CLI installed. +- Only Curvenote staff can create sites — you’ll use our onboarding form. -## Steps - -### 1. Request a Site -- Fill out the [Site Setup Request Form](https://forms.gle/Y8ppqCpPFKPH5GFr7) +## Request a Site +- Fill out the [Site Setup Request Form](https://forms.gle/Y8ppqCpPFKPH5GFr7) - Curvenote will set up: - - Title & subdomain (`my-lab.curve.space`) - - Public/private visibility - - Initial landing content -- Receive confirmation email when live - -### 2. Manage Landing Content -- Landing page = main entry point for visitors -- Update via **web admin** -- Feature articles, collections, or projects -- Configure your hero banner to highlight key work — see [Hero Unit & Background Images](planning.md) -- More planning tips in [Planning Your Site](planning.md) + - **Title & subdomain** (e.g., `my-lab.curve.space`) + - **Public or private** visibility + - **Initial landing content** +- You’ll receive a confirmation email once your site is live. -### 3. Manage Submissions -- Contributors submit via: - ```bash - curvenote submit ``` - -- Review & publish as admin -- See [Publish & Share] (publish-article.md) +## Next Steps After Creation +- Review your site’s landing page. +- Follow the [Manage Your Site →](manage-site.md) guide to update content and handle submissions. -## 4.Repo Setup Pattern (Git/GitHub) -- `content/` for articles -- `assets/` for figures/images -- Collections in `curvenote.yml` -- See [Organize Content into Sections](organize-content.md) --- ## Related Guides - [Hero Unit & Background Images](planning.md) From 331a2acbe8cf616e74f976dcfa45abe077b47f7b Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Fri, 15 Aug 2025 23:55:01 -0600 Subject: [PATCH 25/26] Fix broken references to figures --- getting-started/create-a-site.md | 38 ++++++++------ getting-started/create-article-cli.md | 41 +++++++-------- getting-started/create-project.md | 75 +++++++++++++-------------- getting-started/install-cli.md | 56 ++++++++++---------- getting-started/publish-article.md | 55 ++++++++++---------- getting-started/what-is-curvenote.md | 41 ++++++--------- 6 files changed, 148 insertions(+), 158 deletions(-) diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index ac369c1..f897d7f 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -3,28 +3,34 @@ title: Create a Site short_title: Create a Site --- -**Objective:** -Request a Curvenote site so you can publish and share your work online. +# Create a Site -## Before You Start -- Curvenote account + CLI installed. -- Only Curvenote staff can create sites — you’ll use our onboarding form. +## Quick Start +Set up your Curvenote site to publish and share your work online + +Creating a Curvenote site gives you a dedicated space to publish your research, lab work, or any scientific content. The process is simple and handled through our onboarding form. + +## Before you start + +- Curvenote account + CLI installed +- Only Curvenote staff can create sites — you'll use our onboarding form + +## Request a site -## Request a Site - Fill out the [Site Setup Request Form](https://forms.gle/Y8ppqCpPFKPH5GFr7) - Curvenote will set up: - **Title & subdomain** (e.g., `my-lab.curve.space`) - **Public or private** visibility - **Initial landing content** -- You’ll receive a confirmation email once your site is live. +- You'll receive a confirmation email once your site is live -## Next Steps After Creation -- Review your site’s landing page. -- Follow the [Manage Your Site →](manage-site.md) guide to update content and handle submissions. +## Next steps after creation ---- -## Related Guides -- [Hero Unit & Background Images](planning.md) -- [Planning Your Site](planning.md) -- [Publish & Share](publish-article.md) -- [Organize Content into Sections](organize-content.md) +- Review your site's landing page +- Follow the [Site Management →](../sites/index.md) guide to update content and handle submissions + +## Related guides + +- [Planning Your Site →](../site-design/planning.md) +- [Publish & Share →](publish-article.md) +- [Organize Content into Sections →](../authoring/organize-content.md) diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index 29a76cb..f46cdd0 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -3,37 +3,38 @@ title: Write Your First Article short_title: Write Article --- - # Write Your First Article -**Goal:** Create and edit your first article in Curvenote using the CLI. - +## Quick Start +Create and edit your first article in Curvenote using the CLI +Writing articles in Curvenote is straightforward and flexible. You can use Markdown, Jupyter notebooks, or other formats to create rich, interactive content. -## 1. Create a New Article +## Create a new article -To create a new article, simply add a new Markdown file to your project’s content/ directory using your preferred text editor or IDE. +To create a new article, simply add a new Markdown file to your project's content/ directory using your preferred text editor or IDE. For example, create a file called `my-first-article.md`: -```bash +``` content/ ├── index.md └── my-first-article.md ``` + Each article should start with YAML frontmatter containing at least a title field. For example: -```bash +```yaml --- title: My First Article date: 2025-08-15 --- ``` -Once created, you can add the new article to your site navigation by editing `curvenote.yml` and linking to the file. -💡 **Tip**: If your project is already linked to a Curvenote site, you can use curvenote push to sync changes for review or curvenote submit to send it to a collection. +Once created, you can add the new article to your site navigation by editing `curvenote.yml` and linking to the file. +💡 **Tip**: If your project is already linked to a Curvenote site, you can use `curvenote push` to sync changes for review or `curvenote submit` to send it to a collection. -## 2. Open and Edit Your Article +## Open and edit your article Open the new file in your preferred text editor (for example, VS Code, Sublime Text, or another editor you use). @@ -41,10 +42,10 @@ If you use Visual Studio Code, you can open the file directly from your terminal ```bash code content/my-first-article.md ``` -You can write in **MyST Markdown** or use **Jupyter Notebooks**. +You can write in **MyST Markdown** or use **Jupyter Notebooks**. -## 3. Preview Locally +## Preview locally See your changes instantly by running: @@ -54,18 +55,14 @@ curvenote start This opens a local preview of your site in your browser so you can check formatting, figures, and links. +## Organize your articles -## 4. Organize Your Articles - -For best practices on organizing content, see [Organize Articles and Sections](.organize-content.md) - - -## Next Steps +For best practices on organizing content, see [Organize Articles and Sections](../authoring/organize-content.md) -Once your article looks good, you can: +## Next steps -1. [Publish & Share →](./publish-article.md) -2. [Add Figures, Images, and Media →](../authoring/add-figures-media.md) -3. [Link Data and Code →](../authoring/link-data-code.md) +- [Publish & Share →](./publish-article.md) +- [Add Figures, Images, and Media →](../editor/figures-and-images.md) +- [Link Data and Code →](../editor/add-and-link-notebooks.md) diff --git a/getting-started/create-project.md b/getting-started/create-project.md index d8f322e..c09f419 100644 --- a/getting-started/create-project.md +++ b/getting-started/create-project.md @@ -5,51 +5,52 @@ short_title: Create Project # Create Your First Project -**Goal:** Create and organize your first Curvenote project so you can start writing and publishing content. - - -## 1. What’s a Project in Curvenote? +## Quick Start +Create and organize your first Curvenote project to start writing and publishing content A **project** is the container for everything you want to publish in Curvenote — including articles, figures, datasets, media, and the configuration that controls how they appear online. -A project can be: -- **A single article** — for example, a preprint, report, or tutorial. -- **A multi-article collection** — such as a lab website, conference proceedings, or journal issue. -- **A research output with multiple parts** — combining text, interactive figures, and linked data/code. +## What's a project in Curvenote? -The `curvenote.yml` file defines the project’s metadata, structure, and publishing settings, whether your project is just one file or a large collection. +A project can be: +- **A single article** — for example, a preprint, report, or tutorial +- **A multi-article collection** — such as a lab website, conference proceedings, or journal issue +- **A research output with multiple parts** — combining text, interactive figures, and linked data/code +The `curvenote.yml` file defines the project's metadata, structure, and publishing settings, whether your project is just one file or a large collection. Projects typically include: -- **Configuration file** (`curvenote.yml`) — **Required.** Defines site settings, article metadata, and publishing options. -- **Content files** — Any `.md`, `.ipynb`, or `.tex` files containing your articles, sections, and figures. These can be organized in any folder structure. -- **Supporting files** — Images, datasets, scripts, or other media used in your articles. These can be stored anywhere in the project. +- **Configuration file** (`curvenote.yml`) — **Required.** Defines site settings, article metadata, and publishing options +- **Content files** — Any `.md`, `.ipynb`, or `.tex` files containing your articles, sections, and figures. These can be organized in any folder structure +- **Supporting files** — Images, datasets, scripts, or other media used in your articles. These can be stored anywhere in the project There is no required folder naming convention; organize files and directories in the way that best suits your workflow. - -## 2. Create a New Project +## Create a new project From your terminal: ```bash curvenote init ``` -When you run this command, you’ll be prompted to choose how to initialize the project: -## 1. Import from Curvenote — Pulls content from the legacy web editor at curvenote.com. -*Note: This workflow is not recommended for new projects and may be removed in future versions.* +When you run this command, you'll be prompted to choose how to initialize the project: + +### 1. Import from Curvenote +Pulls content from the legacy web editor at curvenote.com. +*Note: This workflow may be removed in future versions.* -## 2. Use the content in this folder — Treats the current folder as a Curvenote project using the existing files inside it. +### 2. Use the content in this folder +Treats the current folder as a Curvenote project using the existing files inside it. -- This option is only available if the folder already contains content (e.g., `.md`, .`ipynb`, .`tex` files) and you are starting from that folder. +- This option is only available if the folder already contains content (e.g., `.md`, `.ipynb`, `.tex` files) and you are starting from that folder -For new projects, we recommend starting in a folder where you’ve already added your initial article or content files. +For new projects, we recommend starting in a folder where you've already added your initial article or content files. Then, run `curvenote init` from that folder to create the required curvenote.yml configuration file and begin organizing your content. -## 3. Navigate and Explore +## Navigate and explore Move into your new project folder: @@ -57,21 +58,19 @@ Move into your new project folder: cd my-first-project ``` -Open `/index.md` in your editor — this is your first article. -You can rename it, add more `.md` or `.myst.md`, `ipynb` or `.tex` files, and organize them in folders that make sense for your project. +Open `/index.md` in your editor — this is your first article. You can rename it, add more `.md` or `.myst.md`, `ipynb` or `.tex` files, and organize them in folders that make sense for your project. - -## 4. Organize Your Content +## Organize your content Best practices (adapt as needed for your workflow): -- **One article per file** for clarity. -- Group related articles into folders (e.g., `/methods`, `/results`). -- Store images and figures wherever is most convenient — for example, alongside the articles that reference them, or in a dedicated folder like `assets/` or `media/`. -- Use clear, short file names (avoid spaces). +- **One article per file** for clarity +- Group related articles into folders (e.g., `/methods`, `/results`) +- Store images and figures wherever is most convenient — for example, alongside the articles that reference them, or in a dedicated folder like `assets/` or `media/` +- Use clear, short file names (avoid spaces) Example: -```arduino +``` methods/ ├── data-collection.md └── analysis.md @@ -83,7 +82,7 @@ assets/ └── dataset.csv ``` -## 5. Check Your Setup +## Check your setup You can preview your content locally by running: @@ -93,14 +92,10 @@ curvenote start This launches a local development server where you can see your project as it will appear online. -## Next Steps - -Now that you have a project: +## Next steps -1. [Write Your First Article](create-article-cli.md) -2. [Publish & Share](publish-article.md) -3. [Set Up a Site →](create-a-site.md) - ---- +- [Write Your First Article →](create-article-cli.md) +- [Publish & Share →](publish-article.md) +- [Set Up a Site →](create-a-site.md) -💡 **Tip:** You can connect your project to GitHub for version control. See [Connect to GitHub](../integrations/github.md). \ No newline at end of file +💡 **Tip:** You can connect your project to GitHub for version control. See [Submissions Using GitHub](submissions-using-github.md). \ No newline at end of file diff --git a/getting-started/install-cli.md b/getting-started/install-cli.md index 9eb9fca..fe42a71 100644 --- a/getting-started/install-cli.md +++ b/getting-started/install-cli.md @@ -5,24 +5,24 @@ short_title: Install CLI # Install & Authenticate the Curvenote CLI +## Quick Start +Get the Curvenote CLI installed and authenticated in minutes -**Goal:** -Install the Curvenote command-line tool, log in, and ensure you're ready to create and publish content. +The Curvenote CLI lets you create, manage, and publish content from your terminal. Follow these steps to get up and running quickly. - -## Before You Start +## Before you start Make sure you have: **Node.js v18 or later** (comes with `npm`) - - Check your version: - ```bash - node --version - ``` - - If needed, [download Node.js](https://nodejs.org/) or install via Conda: - ```bash - conda install -c conda-forge nodejs - ``` +- Check your version: + ```bash + node --version + ``` +- If needed, [download Node.js](https://nodejs.org/) or install via Conda: + ```bash + conda install -c conda-forge nodejs + ``` ## 1. Install the CLI @@ -30,40 +30,42 @@ Open your terminal and run: ```bash npm install -g curvenote - ``` + Verify installation: ```bash curvenote --version ``` + You should see a version number. If you see an error, check your Node.js and `npm` setup. ## 2. Authenticate with Curvenote -You’ll need an API token if working with private projects or publishing to a site. +You'll need an API token if working with private projects or publishing to a site. -1. In your Curvenote Personal Settings, generate a new API token. +1. In your Curvenote Personal Settings, generate a new API token 2. In your terminal, run: -```bash -curvenote token set -``` -3. Paste the API tocken when prompted. + ```bash + curvenote token set + ``` +3. Paste the API token when prompted For more options, see the full [Authentication Reference](../cli/authentication.md). -## 3. Verify Your Setup +## 3. Verify your setup + Run: ```bash curvenote token check ``` + If it returns your username, your CLI is ready. -## Next Steps +## Next steps -1. [Create Your First Project](create-project.md) -2. [Write Your First Article from the CLI](create-article-cli.md) -3. [Set Up a Site for Publishing](create-a-site.md) -4. [Push, Submit, and Publish Content](push-submit-publish.md) +- [Create Your First Project →](create-project.md) +- [Write Your First Article from the CLI →](create-article-cli.md) +- [Set Up a Site for Publishing →](create-a-site.md) +- [Publish & Share Content →](publish-article.md) -💡 **Tip:** The Curvenote CLI is open source—[view it on GitHub](https://github.com/curvenote/curvenote). -::: +💡 **Tip:** The Curvenote CLI is open source—[view it on GitHub](https://github.com/curvenote/curvenote). diff --git a/getting-started/publish-article.md b/getting-started/publish-article.md index c35c039..ef03612 100644 --- a/getting-started/publish-article.md +++ b/getting-started/publish-article.md @@ -3,28 +3,28 @@ title: Publish & Share Your Article short_title: Publish & Share --- +# Publish & Share Your Article -# Publish & Share +## What you'll learn +How to publish your article and make it accessible online -**Goal:** Publish your article or site so it’s live on the web. +Publishing your article with Curvenote is simple and fast. Whether you want to share your research publicly or submit it for review, Curvenote makes it easy to get your content live on the web. ---- +## Before you publish -## Before You Publish -Check that your project has: -- At least one article with content. -- A valid `curvenote.yml` configuration file. -- All required assets (figures, datasets, notebooks) included. +Make sure your project is ready: -If you’re not sure your site is configured, see [Set Up a Site](set-up-site.md) +- At least one article with content +- A valid `curvenote.yml` configuration file +- All required assets (figures, datasets, notebooks) included ---- +If you're not sure your site is configured, see [Set Up a Site](create-a-site.md) -## Choose How You Want to Publish +## Choose how to publish -**Publish directly to the web (public)** +**Publish directly to the web (public)** -This puts your project live on the `.curve.space` domain you set in `site.domains` +This puts your project live on the `.curve.space` domain you set in `site.domains`: ```bash curvenote deploy @@ -32,31 +32,32 @@ curvenote deploy **Submit to a site (for review or staged publishing)** -Send your project to a site (e.g., a lab site or journal). Only site admins can make it public. +Send your project to a site (e.g., a lab site or journal). Only site admins can make it public: + ```bash curvenote submit ``` If you have admin rights and want to publish from the CLI: + ```bash curvenote submission publish ``` -## See the Result -- **Deploy:** The CLI will show your live `.curve.space` URL. -- **Submit:** Your submission appears in the site’s admin area. - If published, the site will provide the public URL. +## See the result -## Update Content -- If you deployed: Run `curvenote deploy` again to replace the live version. -- If you submitted: Run `curvenote submit ` to create a new submission version, then publish (via admin UI or `curvenote submission publish `). +- **Deploy:** The CLI will show your live `.curve.space` URL +- **Submit:** Your submission appears in the site's admin area. If published, the site will provide the public URL -## Next Steps +## Update your content -- [Add Figures, Images, and Media →](add-figures-media.md) -- [Link Data and Code →](link-data-code.md) -- [Export to PDF/Typst →](export-pdf.md) +- **If you deployed:** Run `curvenote deploy` again to replace the live version +- **If you submitted:** Run `curvenote submit ` to create a new submission version, then publish (via admin UI or `curvenote submission publish `) ---- +## Next steps + +- [Add Figures, Images, and Media →](../editor/figures-and-images.md) +- [Link Data and Code →](../editor/add-and-link-notebooks.md) +- [Export to PDF/Typst →](../editor/export-pdf.md) -**Tip:** Published content is “living” in Curvenote — you can make edits anytime, and your audience will always see the latest version. +💡 **Tip:** Published content is "living" in Curvenote — you can make edits anytime, and your audience will always see the latest version. diff --git a/getting-started/what-is-curvenote.md b/getting-started/what-is-curvenote.md index 926fe5e..b205cc5 100644 --- a/getting-started/what-is-curvenote.md +++ b/getting-started/what-is-curvenote.md @@ -3,22 +3,25 @@ title: What is Curvenote? short_title: What is Curvenote --- -# What is Curvenote? +# Get Started -Curvenote is a platform for **writing, organizing, and publishing scientific content**—built by researchers, for researchers. +## Welcome +Learn about Curvenote and how to get started -It helps you move beyond static PDFs by enabling **interactive, modular, and versioned scientific outputs**. Whether you're drafting a preprint, creating a lab website, or sharing reproducible analyses, Curvenote provides the tools to publish with **structure, transparency, and flexibility**. +Curvenote is a platform for **writing, organizing, and publishing scientific content**—built by researchers, for researchers. Add your text, datasets, and figures to create interactive, modular, and versioned scientific outputs that move beyond static PDFs. -## A new kind of scientific output +## What makes Curvenote different? -Most research outputs today are frozen in time—locked into PDFs and detached from their underlying data, code, and figures. Curvenote takes a different approach: +Curvenote helps you move beyond static PDFs by enabling: - **Modular articles** with reusable blocks and components - **Versioned content** that tracks every change - **Web-first publishing** for better discoverability - **One-click exports** to Typst or PDF when needed -Work in your browser or use the Curvenote CLI: +## How it works + +Work in your browser or use the Curvenote CLI: - Write in **Markdown, Jupyter**, or the Curvenote editor - Organize content into **folders, articles, and blocks** @@ -26,19 +29,9 @@ Work in your browser or use the Curvenote CLI: - Publish to the web with a single command - Export to Typst or PDF for review or submission ---- - -## The platform for modern research - -Curvenote modernizes how scientific research is written, managed, and published. With Curvenote, you can publish: +## Built for research teams -- Single articles -- Multi-article collections (lab sites, conference proceedings, documentation) -- Research outputs with **interactive figures, notebooks, and citations** - - -## Built for research teams -Curvenote supports: +Curvenote supports collaborative research with: - Collaborative editing & version tracking - Reusable figures, text blocks, and citations @@ -46,12 +39,8 @@ Curvenote supports: - Research integrity checks (iThenticate, Proofig) - Compliance with open science, funder, and institutional policies +## Next steps -## Why it matters -Scientific knowledge should be **open, versioned, and reusable**. Curvenote provides the infrastructure for **living research outputs** that evolve with your work. Our platform organizes research into modular, discoverable components that work across any project, enabling collaborative web-first workflows that connect with your existing tech stack. - - -## Next steps -1. [Install the CLI](getting-started/install-cli.md) -2. [Set up your first publishing site](getting-started/create-a-site.md) -3. [Write and publish your first article](getting-started/create-article-cli.md) \ No newline at end of file +- [Install the CLI →](install-cli.md) +- [Set up your first publishing site →](create-a-site.md) +- [Write and publish your first article →](create-article-cli.md) \ No newline at end of file From 5978cec35bef52b0155f3a19b151337ff16f2d3d Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Sat, 16 Aug 2025 01:29:44 -0600 Subject: [PATCH 26/26] Enhance documentation for Jupyter integration and citation management - Updated "Writing a Scientific Paper using Jupyter" to "Write a Scientific Paper using Jupyter" with detailed sections on setup, structure, and best practices. - Expanded "Add & Link Notebooks" with clearer instructions for uploading and linking notebooks. - Revised "Citations" to "Add Citations and References" with improved guidance on adding citations from DOIs and BibTeX files. - Updated "Figures & Images" to "Add Figures, Images, and Media" with comprehensive steps for adding and formatting media. - Enhanced "Interactive Outputs" with detailed instructions for importing and referencing Jupyter outputs in articles. --- authoring/jupyter-notebooks.md | 161 +++++++++++++++++++++++++- editor/add-and-link-notebooks.md | 71 ++++++++++-- editor/citations.md | 184 +++++++++++++++--------------- editor/figures-and-images.md | 189 ++++++++++++++++--------------- editor/interactive-outputs.md | 88 ++++++++++++-- 5 files changed, 489 insertions(+), 204 deletions(-) diff --git a/authoring/jupyter-notebooks.md b/authoring/jupyter-notebooks.md index 1586cc5..515e6af 100644 --- a/authoring/jupyter-notebooks.md +++ b/authoring/jupyter-notebooks.md @@ -1,8 +1,161 @@ --- -title: Writing a Scientific Paper using Jupyter +title: Write a Scientific Paper using Jupyter short_title: Write using Jupyter --- -:::{important} More Coming Soon! 🚧 -We are actively working on the documentation. Please check back soon or send us an email asking about this page: [support@curvenote.com](mailto:support@curvenote.com) -::: +# Write a Scientific Paper using Jupyter + +## Quick Start +Create scientific papers directly from Jupyter notebooks with integrated code, outputs, and narrative text + +Jupyter notebooks provide a powerful way to write scientific papers that combine code, analysis, visualizations, and narrative text in a single document. Curvenote enhances this workflow by adding version control, collaboration, and publishing capabilities. + +## Before You Start + +Make sure you have: +- Jupyter Lab or Jupyter Notebook installed +- A Curvenote project set up +- Your research data and analysis ready +- A clear structure for your paper + +## 1. Set Up Your Jupyter Environment + +Start with a well-organized Jupyter notebook: + +1. **Create a new notebook** in Jupyter Lab or Jupyter Notebook +2. **Organize your notebook** with clear sections: + - Introduction and background + - Methods and data + - Analysis and results + - Discussion and conclusions +3. **Use markdown cells** for narrative text between code cells +4. **Execute all cells** to ensure outputs are generated + +## 2. Structure Your Paper + +Organize your notebook to follow scientific paper conventions: + +### Introduction Section +- **Background and context** in markdown cells +- **Literature review** with citations +- **Research questions** and objectives +- **Hypotheses** to be tested + +### Methods Section +- **Data collection** procedures +- **Code for data preprocessing** +- **Analysis methods** with clear comments +- **Statistical approaches** used + +### Results Section +- **Code for analysis** with outputs +- **Figures and visualizations** +- **Statistical results** and tables +- **Key findings** in markdown + +### Discussion Section +- **Interpretation** of results +- **Comparison** with previous work +- **Limitations** and future work +- **Conclusions** and implications + +## 3. Add Rich Content + +Enhance your paper with various content types: + +### Code and Analysis +```python +# Example analysis code +import pandas as pd +import matplotlib.pyplot as plt + +# Load and process data +data = pd.read_csv('experiment_data.csv') +results = analyze_data(data) + +# Create visualization +plt.figure(figsize=(10, 6)) +plt.plot(results['x'], results['y']) +plt.title('Experimental Results') +plt.show() +``` + +### Narrative Text +Use markdown cells for: +- **Explanations** of methods and results +- **Citations** and references +- **Context** and background information +- **Discussion** of implications + +### Interactive Elements +- **Interactive plots** (Plotly, Bokeh) +- **Data tables** with sorting/filtering +- **Embedded widgets** for exploration +- **Dynamic visualizations** + +## 4. Link to Curvenote + +Connect your Jupyter notebook to Curvenote: + +1. **Upload your notebook** to your Curvenote project +2. **Link to local file** for version control +3. **Sync changes** automatically +4. **Collaborate** with co-authors + +## 5. Format for Publication + +Prepare your notebook for publication: + +1. **Review all outputs** are properly displayed +2. **Check markdown formatting** is correct +3. **Verify citations** are properly formatted +4. **Test interactive elements** work as expected +5. **Export to various formats** (PDF, HTML, etc.) + +## 6. Collaborate and Review + +Work with co-authors effectively: + +1. **Share your project** with collaborators +2. **Use comments** for feedback and discussion +3. **Track changes** with version control +4. **Review and revise** collaboratively +5. **Finalize** for submission + +## Best Practices + +### Code Organization +- **Clear variable names** and comments +- **Modular functions** for reusability +- **Error handling** for robustness +- **Documentation** for complex algorithms + +### Writing Style +- **Clear, concise language** in markdown cells +- **Proper scientific tone** and terminology +- **Logical flow** between sections +- **Consistent formatting** throughout + +### Data Management +- **Reproducible code** with fixed random seeds +- **Data versioning** and backup +- **Clear data sources** and citations +- **Open data** when possible + +## Next Steps + +- [Add Interactive Outputs →](../editor/interactive-outputs.md) +- [Link Data and Code →](../editor/add-and-link-notebooks.md) +- [Publish & Share Your Article →](../getting-started/publish-article.md) + +--- + +💡 **Tip:** Jupyter notebooks in Curvenote maintain full interactivity when published, allowing readers to explore your analysis, run code, and interact with visualizations directly in the browser. + +⚡ **Important: +Reproducible Research Best Practices** + +- Always include all necessary code and data +- Use version control for your notebooks +- Document your environment and dependencies +- Test that your notebook runs from start to finish diff --git a/editor/add-and-link-notebooks.md b/editor/add-and-link-notebooks.md index 989f869..e8ddf3d 100644 --- a/editor/add-and-link-notebooks.md +++ b/editor/add-and-link-notebooks.md @@ -1,25 +1,76 @@ --- title: Add & Link Notebooks +short_title: Add & Link Notebooks --- +# Add & Link Notebooks + +## Quick Start +Upload Jupyter notebooks to your Curvenote project and link them to local files for version control and collaboration + Notebooks can be created in Jupyter then uploaded to a Curvenote project via the web app. You should always add pre-executed, saved notebooks to Curvenote so that outputs appear and are available for use. Notebooks that already exist on Curvenote can also be imported and linked to a local `.ipynb` file. -## Upload a Notebook - Curvenote +## Before You Start -You can upload a Jupyter notebook to a Curvenote **project**. To upload an existing notebook: +Make sure you have: +- A Curvenote project open +- A Jupyter notebook (`.ipynb` file) ready to upload +- The notebook is saved with executed outputs (if you want to display results) -- In the project navigation panel - - Click the **Upload ☁️⬆️** icon -- Click to browse or drag and drop an `.ipynb` file from your computer - - Click **DONE** +## 1. Upload a Notebook to Curvenote -```{danger} -The upload process for notebooks on Curvenote should only be used if you do not intend to run the notebook! The local copy of your notebook will not be linked to Curvenote (it does not contain the necessary metadata for versioning). If you need to run this notebook you will have to manually link your local copy. Learn more [Add & Link Notebooks](./add-and-link-notebooks.md). +To upload an existing Jupyter notebook to your project: -``` +1. **Open your project** in the Curvenote web app +2. **In the project navigation panel:** + - Click the **Upload ☁️⬆️** icon +3. **Add your notebook:** + - Click to browse and select your `.ipynb` file + - Or drag and drop the file from your computer +4. **Click "DONE"** to complete the upload -```{figure} images/m59m7JQmWVyPjlASj9v3-UGpUYCC2QlQIhNSTYmEh-v1.mp4 +```{figure} images/m59m7JQmWVyPjlASj9h3-UGpUYCC2QlQIhNSTYmEh-v1.mp4 :name: tdrOpSRldZ :align: center :width: 100% ``` + +## 2. Link Local Notebooks (Recommended) + +For notebooks you plan to continue working on, it's better to link your local copy: + +1. **Upload the notebook** to Curvenote first (following steps above) +2. **In your local project folder:** + - Place your `.ipynb` file in the appropriate directory + - The file should be in the same location relative to your project structure +3. **Curvenote will automatically detect** the local file and link it +4. **Future changes** to your local notebook will sync with Curvenote + +## 3. Use Notebooks in Your Articles + +Once uploaded, you can: + +- **Display notebook outputs** as figures in your articles +- **Reference specific cells** from your notebooks +- **Create interactive elements** that readers can explore +- **Version control** your notebooks alongside your articles + + +⚡ **Important: +Upload vs. Link Workflow** + +- **Upload only**: Use this if you don't plan to run the notebook again +- **Link local file**: Use this if you need to continue working on the notebook + +The upload process does not create a link to your local file, so you'll need to manually link it if you want to continue editing. + + +## Next Steps + +- [Add Figures, Images, and Media →](./figures-and-images.md) +- [Create Interactive Outputs →](./interactive-outputs.md) +- [Work with Jupyter Notebooks →](../authoring/jupyter-notebooks.md) + +--- + +💡 **Tip:** Always save your notebooks with executed outputs before uploading to Curvenote. This ensures that figures, charts, and other results are visible in your articles. diff --git a/editor/citations.md b/editor/citations.md index e75bab9..b20e3ae 100644 --- a/editor/citations.md +++ b/editor/citations.md @@ -1,131 +1,135 @@ --- -title: Citations +title: Add Citations and References +short_title: Citations --- -You can easily add citations to your Curvenote articles and have quick access to them while you are typing. There are currently two ways to add references: +# Add Citations and References -1. **From a DOI**\: Simply search the document or article DOI, and add it to your article with one-click! -2. **From a BibTex file**\: Export from your reference manager (e.g. Zotero, Mendeley, etc.) as a BibTex file, and drag and drop into Curvenote. If you want easy access to a reference manager, without downloading anything we recommend . +## Quick Start +Add citations to your Curvenote articles using DOIs or BibTeX files with automatic formatting and reference management -Once your citations have been added to your project, you can easily access them through the `/cite` command, and can click on the citation to see all the details - and you can click on it to navigate to the web article or document. For example, try clicking on this citation {cite:p}`Cockett2015SimPEG`. +You can easily add citations to your Curvenote articles and have quick access to them while you are typing. Citations can be added from DOIs or imported from BibTeX files, and they're automatically formatted according to your chosen style. -## Video Demo 📺 - -```{iframe} https://www.loom.com/embed/646329caf1e74c39bd6abb3835717ce0 -:label: YtpswdIs9H -:align: center -:width: 80% -``` - -```{list-table} Example of rendered citations, try clicking on any of the citations! -:header-rows: 1 -:name: jBqbQidSUR - -* - - - - Parenthetical citation - - - Narrative citation +## Before You Start -* - 1 author +Make sure you have: +- An article open in Curvenote +- DOIs for papers you want to cite, or +- A BibTeX file exported from your reference manager +- Your citation library set up in your project - - {cite:p}`heinen_compensation_2014` - - - {cite:t}`heinen_compensation_2014` - -* - 2 authors - - - {cite:p}`Bartkowski2018Leverage` - - - {cite:t}`Bartkowski2018Leverage` +## Video Demo 📺 -* - 3 or more authors +[Watch the video tutorial](https://www.loom.com/embed/646329caf1e74c39bd6abb3835717ce0) - - {cite:p}`winter_effects_2018` +## 1. Add Citations from DOIs - - {cite:t}`winter_effects_2018` +A digital object identifier (DOI) is a unique string that permanently identifies an article or document on the web. -* - Group author +### Find the DOI +1. **Locate the DOI** on the article or document you want to cite +2. **Copy it to your clipboard** +3. **Note**: If you can't find the DOI, use the 'Search Metadata' option on [crossref.org](https://crossref.org) - - {cite:p}`EuropeanCommission2020` +### Add the Citation +1. **Place your cursor** where you want to add the citation +2. **Type `/cite`** to access the citation menu +3. **Navigate to "ADD DOI"** +4. **Enter the DOI** in the search bar +5. **Click "SEARCH"** +6. **Select "CREATE CITATION"** if the correct article appears - - {cite:t}`EuropeanCommission2020` -``` +## 2. Import Citations from BibTeX Files -## Adding citations through DOIs +BibTeX files (`.bib`) are commonly used with LaTeX and can be exported from most reference managers like Zotero, Mendeley, or EndNote. -A digital object identifier (DOI) is a unique string that’s used to permanently identify an article or document on the web. If you are citing a paper, it will have a searchable DOI you can add to your Curvenote citation library. +### Export from Reference Manager +1. **Open your reference manager** (Zotero, Mendeley, etc.) +2. **Select the references** you want to import +3. **Export as BibTeX** (`.bib` format) +4. **Save the file** to your computer -To add a DOI: +### Import to Curvenote +1. **Drag and drop** the `.bib` file into your Curvenote project +2. **Or use the upload button** in your project +3. **All references** will be added to your citation library +4. **Citation keys** will be automatically generated -- Locate the DOI on the article or document you want to cite, and copy it to your clipboard +[Watch video: Importing citations from BibTeX file](images/MshxlXndaLsk3WbJ0ZGy-RaR3QGIKD1ek3VXMAX31-v3.mp4) -```{note} -The DOI is usually included with the article content. However, if you cannot find the DOI you can use the ‘Search Metadata’ option on [crossref.org.](crossref.org.) +## 3. Insert Citations in Your Text -``` +Once citations are in your library, you can easily insert them: -- Place your cursor in the area you want to add the citation -- Access the citation menu by using the `/cite` command -- Navigate to **ADD DOI** -- Enter the DOI in the search bar -- Select **SEARCH** -- If the appropriate article or document is shown, select **CREATE CITATION** +### Single Citation +1. **Place your cursor** where you want the citation +2. **Type `/cite`** or `[[cite:` +3. **Search for the reference** you want to cite +4. **Select the citation** from the dropdown +5. **The citation** will be inserted automatically -```{figure} images/MshxlXndaLsk3WbJ0ZGy-tZmadZXYnXoMbmz0nAwm-v2.mp4 -:name: 17800507 -:align: center -:width: 70% -``` +### Multiple Citations +1. **Place your cursor** where you want the citations +2. **Type `/reference`** to access the references menu +3. **Use the search** to find references +4. **Check the boxes** for citations you want to add +5. **Click "INSERT CITATIONS"** -Your citation will now be added to your citation library for that project, and can be inserted into your articles without having to re-add the DOI. +![Insert multiple citations](images/MshxlXndaLsk3WbJ0ZGy-V58UiaFTTyA5qx1tti7D-v1.png) -## Adding citations from BibTex files +## 4. Format and Arrange Citations -The bibtex (`*.bib`) file format is a storage format for citations, it is commonly used with $\LaTeX$, and can be exported from most reference managers. +### Citation Styles +Citations are automatically formatted according to your chosen style: +- **Parenthetical citations**: `{cite:p}` for (Author, Year) +- **Narrative citations**: `{cite:t}` for Author (Year) -```{figure} images/MshxlXndaLsk3WbJ0ZGy-RaR3QGIKD1ek3VXMAX31-v3.mp4 -:name: adaa6acf -:align: center -:width: 70% +### Group Citations +1. **Select a citation** in your text +2. **Click the `[]` button** in the toolbar to add brackets +3. **Drag citations** into and out of citation groups +4. **Rearrange citations** within groups as needed -Import your references from a `*.bib` file, and easily update your references if you need to! -``` -### Updating Citations +## 5. Update and Manage Citations -If you need to update your citation (e.g. fixing an author name, or adding a date), just re-export the bibtex from your reference manager, ensuring that the citation key for the reference is the same. Then just re-upload, the bibtex and all of the included reference will be updated💥. +### Update Existing Citations +1. **Re-export your BibTeX** from your reference manager +2. **Ensure citation keys** remain the same +3. **Re-upload the BibTeX file** +4. **All references** will be updated automatically -In Curvenote, the references are stored as a `Reference` block, when you upload through a bibtex file it is given a unique `name` that is derived from the citation key you provide. The block `name` (used in the URL and must be unique for a project) is prefixed with `ref-` and is lowercased. This means the bibtex references are like `Cockett2015-Elsevier` becomes `ref-cockett2015-elsevier`. You can also use these keys to quickly look up a citation through the `[[cite:` command or the reference search panel. +### Citation Keys +- **Format**: `ref-citationkey` (lowercase) +- **Example**: `Cockett2015-Elsevier` becomes `ref-cockett2015-elsevier` +- **Use for**: Quick lookup with `[[cite:` command -## Inserting multiple citations +## Citation Examples -To add multiple citations: +| Citation Type | Parenthetical Citation | Narrative Citation | +|---------------|------------------------|-------------------| +| 1 author | (Heinen, 2014) | Heinen (2014) | +| 2 authors | (Bartkowski & Smith, 2018) | Bartkowski and Smith (2018) | +| 3 or more authors | (Winter et al., 2018) | Winter et al. (2018) | +| Group author | (European Commission, 2020) | European Commission (2020) | -- Place your cursor in the area you want to add the citation -- Access the references menu by using the `/reference` command -- Filter using the **Search**, and use the checkboxes to select the citation you would like to add -- Select **INSERT CITATIONS** -The citations will now be added! -```{figure} images/MshxlXndaLsk3WbJ0ZGy-V58UiaFTTyA5qx1tti7D-v1.png -:name: bb7026ea -:align: center -:width: 60% -``` +## Next Steps -## Rearranging Citations +- [Add Figures, Images, and Media →](./figures-and-images.md) +- [Create Internal References →](./internal-references.md) +- [Export to PDF/LaTeX →](./export-latex.md) -By default when citations are added through the `[[cite:` command, they are added as individual citations, these can be wrapped in brackets using the `[]` icon in the toolbar when the citation is selected. You can also drag citations into and out of citation-groups. In latex, these correspond to `\citep{}` and render slightly differently than if you use your own brackets. +--- -```{figure} images/MshxlXndaLsk3WbJ0ZGy-jTbSRxmzUrpQhHBo3ZuF-v3.mp4 -:name: a25010aa -:align: center -:width: 70% +💡 **Tip:** Citations in Curvenote are clickable and will take you directly to the source article or document when clicked. -Use the `[]` button to toggle the brackets around the citation. You can drag citations into different groups, or rearrange them in order. -``` +⚡ **Important: +Citation Management** -Note that if you add the citation through the `/reference` command, then multiple citations will be added to a single group in one go. +- Keep your BibTeX file updated in your reference manager +- Use consistent citation keys across your project +- Regularly sync your references to avoid conflicts +- Test your citations before finalizing your document diff --git a/editor/figures-and-images.md b/editor/figures-and-images.md index 9c9f767..387df5e 100644 --- a/editor/figures-and-images.md +++ b/editor/figures-and-images.md @@ -1,128 +1,137 @@ --- -title: Figures & Images +title: Add Figures, Images, and Media +short_title: Add Figures & Images --- -Images and GIFs can be added into articles by dragging them into a content block, or using the editing menu. Once added, images can be resized, and have numbered captions, which allow you to reference the figures in other parts of your document. +# Add Figures, Images, and Media + +## Quick Start +Add images, GIFs, and other media to your articles with proper formatting, captions, and internal references + +## Before You Start + +Make sure you have: +- An article open in Curvenote +- Images, GIFs, or other media files ready to add +- Content in Draft Mode (click **EDIT** at the top of the page) ## Video Demo 📺 -```{iframe} https://www.loom.com/embed/6aa98f41d6f540cea5b759a1b9b0690f -:label: GlzGgRNG6h -:align: center -:width: 90% -``` +[Watch the video tutorial](https://www.loom.com/embed/6aa98f41d6f540cea5b759a1b9b0690f) + +## 1. Add Images and GIFs + +You can add static images (JPEG, TIFF, PNG) and GIFs using several methods: -## Add Image or GIF +### Method 1: Drag and Drop +- **Drag and drop** images from your computer directly into a content block +- A line will appear as you drag, and your images will appear below that line once dropped -Static image formats (JPEG, TIFF, PNG, etc.) and GIFs are all supported and treated the same throughout Curvenote. To add an image or GIF you can either drag and drop from your computer or copy paste from your clipboard. Images and GIFs must be added to an existing content block when they are first added to Curvenote. After they have been added, they can be copied out via their oxa link and pasted as their own block within an article or notebook. +### Method 2: Copy and Paste +- **Paste** images directly from your clipboard into a content block +- Images will automatically upload and appear in your content -To add an image/GIF to an existing content block: +### Method 3: Command Menu +- Open the **command menu** by typing `/` +- Search for `image` +- Drag and drop your images into the box or click to browse and select files -- You must be in Draft Mode for the page and block. - - To enter Draft Mode for the page click **EDIT** at the top of the page. - - To enter Draft Mode for the block, double click within the block or select the block and hit `enter`. -- You can use any of the following to add one or multiple images/GIFs - - **Drag and drop** images/GIFs from your computer directly into your block - - A line will appear as you drag, and once you drop your images will appear below that line - - **Paste** images/GIFs directly into your block - - Open the **command menu** `/` and search for `image` then - - Drag and drop your images/GIFs into the box - - Click within the box to browse and select your files - - Open the **insert menu** in the editing toolbar and select **Image** then - - Drag and drop your images/GIFs into the box - - Click within the box to browse and select your files -- The transparency may pulse while the images/GIFs uploads. +### Method 4: Insert Menu +- Open the **insert menu** in the editing toolbar +- Select **Image** +- Drag and drop your images into the box or click to browse and select files -To display an image/GIF as its own block: +![Add images using drag and drop](images/Z1isOjJQGvM22q5fhunb-N5l1Q6oYXvf6h3LU4dRz-v1.png) -- You must be in Draft Mode for the page. - - To enter Draft Mode for the page click **EDIT** at the top of the page. -- Select the block above where you want to add your image/GIF. - - You may need to hit `esc` until the entire block is selected or click directly on the block selection tab (it will be a slightly darker blue). -- Paste your image/GIF. -- A new block will appear below that is just your image/GIF. +## 2. Create Standalone Image Blocks -```{figure} images/Z1isOjJQGvM22q5fhunb-N5l1Q6oYXvf6h3LU4dRz-v1.png -:name: uqtMbuXPbG -:align: center -:width: 70% -``` +To display an image as its own block (separate from text): -## Formatting +1. **Enter Draft Mode** for the page (click **EDIT** at the top) +2. **Select the block** above where you want to add your image + - You may need to hit `esc` until the entire block is selected + - Or click directly on the block selection tab (darker blue area) +3. **Paste your image** - a new block will appear below with just your image -Once your image, GIF, video or IFrame has uploaded, you’ll see a toolbar which will allow you to format your content. You’ll be able to adjust the alignment, change the width, or delete it. +## 3. Format Your Images -```{figure} images/Z1isOjJQGvM22q5fhunb-Dp770ojYtbrTmXDe2Gy0-v1.png -:name: CYtDPoRVUr -:align: center -:width: 70% -``` +Once uploaded, you'll see a formatting toolbar that allows you to: -## Image and GIF Settings +- **Adjust alignment** (left, center, right) +- **Change width** (percentage of page width) +- **Delete** the image if needed -Images and GIFs are a special type of blocks in Curvenote. As shown above they can be displayed on their own within an article or notebook. They also have their own settings and versioning. Both can be used as a Figure with numbering, captions, and internal referencing within your content. +![Format images with toolbar](images/Z1isOjJQGvM22q5fhunb-Dp770ojYtbrTmXDe2Gy0-v1.png) -### Versioning +## 4. Create Figures with Captions and Numbering -No matter if your image/GIF is displayed as its own block or within another block, it is versioned independently. New versions are created when you replace the image or update the image caption. When the image/GIF is selected, you can access the previous versions and choose to use them as you would a block, in the Block Details Panel. +Images and GIFs can be formatted as **Figures** with automatic numbering and captions: -Replacing an image/GIF will create a new version of the image/GIF block. To replace a block (not delete it): +1. **Select the image** you want to format as a figure +2. **In the formatting toolbar:** + - Click the lines symbol for **Show/Hide Caption** + - When caption is shown, click the number icon for **Toggle Numbering** -- Select the image/GIF you want to replace. -- Drag and drop or paste a new image onto the previous. +Figures are automatically numbered by their location on the page, starting at 1. -To use a different version of an image/GIF: +![Create figures with captions](images/Z1isOjJQGvM22q5fhunb-sIdK5tPBxpH5QPoljim3-v1.png) -- Select the image/GIF. -- Expand the **Block Details Panel** on the right of the page. -- Select a version you want to use. - - A preview of that version will appear in place of the current image/GIF. -- Click **USE VERSION**. +## 5. Reference Figures in Your Text -```{figure} images/Z1isOjJQGvM22q5fhunb-XSFXHCb26Y6uqqkIhsXz-v1.png -:name: PJnQP46ZMR -:align: center -:width: 70% -``` +You can reference figures by their numbers using internal references: -### Settings +### Method 1: Command Menu +- Type `/link to figure` in your text +- Select the figure you want to reference from the dropdown menu -You can access and update the image/GIF block settings when the it is displayed either in a content block or on its own. The settings for an image/GIF block include the URL, title, description, image caption, and tags. The description for an image/GIF block is not displayed, as opposed to the image caption which can be displayed below the image/GIF and in the hover feature if the figure is referenced. +### Method 2: Keyboard Shortcut +- Type `[[fig:` in your text +- Select the figure you want to reference from the dropdown menu -To update the image/GIF settings: +When readers click on the reference, a preview of the image and its caption is displayed. -- Open Image Settings. - - For and image/GIF inside a content block - - Open the $\mathbf{\vdots}$ **Options** menu to the top-right of the image. - - Select **Image Settings**. - - For a stand-alone image/GIF block - - Open the $\mathbf{\vdots}$ **Options** menu to the top-right of the block. - - Select **Block Settings**. -- Update the settings. -- Click **UPDATE SETTINGS**. +## 6. Manage Image Versions -### Figures +Images are versioned independently in Curvenote. New versions are created when you: +- Replace the image +- Update the image caption -Image and GIFs can be formatted as Figures within your content on Curvenote. This means that they can be numbered, have captions displayed, and referenced throughout your text. +### Replace an Image +1. **Select the image** you want to replace +2. **Drag and drop or paste** a new image onto the previous one +3. A new version will be created automatically -To toggle the caption and or numbering for an image/GIF: +### Use a Previous Version +1. **Select the image** +2. **Expand the Block Details Panel** on the right of the page +3. **Select a version** you want to use + - A preview will appear in place of the current image +4. **Click "USE VERSION"** -- Select the image. -- In the formatting toolbar that appears: - - Select the lines symbol for the **Show/Hide Caption** option. - - When the caption is shown, you can then enable numbering by selecting the number icon for the **Toggle Numbering** option. +![Manage image versions](images/Z1isOjJQGvM22q5fhunb-XSFXHCb26Y6uqqkIhsXz-v1.png) -Figures can be referenced by their numbers within the text using either the command menu or keyboard shortcuts. To reference a figure use one of the following two commands, then select the figure you want to reference from the drop down menu. When you click on the reference a preview of the image and its caption is displayed. Learn about internal references [Internal References](./internal-references.md) +## 7. Update Image Settings -`/link to figure` `[[fig:` +You can access and update image settings including URL, title, description, caption, and tags: -```{figure} images/Z1isOjJQGvM22q5fhunb-sIdK5tPBxpH5QPoljim3-v1.png -:name: w1vNkL56vc -:align: center -:width: 50% -``` +### For Images in Content Blocks +1. Open the **⋮ Options menu** to the top-right of the image +2. Select **"Image Settings"** +3. Update the settings as needed +4. Click **"UPDATE SETTINGS"** -```{note} -The numbering is ordered by location of the image/GIF on the page. All numbering will start at 1 at the beginning of the page. The numbering will automatically update with added or removed figures. +### For Standalone Image Blocks +1. Open the **⋮ Options menu** to the top-right of the block +2. Select **"Block Settings"** +3. Update the settings as needed +4. Click **"UPDATE SETTINGS"** + +## Next Steps + +- [Create Internal References →](./internal-references.md) +- [Add Interactive Outputs →](./interactive-outputs.md) +- [Link Data and Code →](./add-and-link-notebooks.md) + +--- -``` +💡 **Tip:** Images and GIFs are treated as special blocks in Curvenote, meaning they can be reused across multiple articles and have their own versioning history. diff --git a/editor/interactive-outputs.md b/editor/interactive-outputs.md index 6a2bfaa..ca58805 100644 --- a/editor/interactive-outputs.md +++ b/editor/interactive-outputs.md @@ -1,19 +1,87 @@ --- -title: Interactive Outputs +title: Add Interactive Outputs +short_title: Interactive Outputs --- -Curvenote is built to work hand in hand with Jupyter and allows you to directly use outputs from Jupyter as figures within your Curvenote articles. The versioning in Curvenote also allows for you to easily update your image in the article, rather than having to copy-and-paste a new static image each time you update your code. Curvenote also supports interactive Jupyter outputs, learn more [Interactive Outputs](./interactive-outputs-in-jupyter.md). +# Add Interactive Outputs -See [Jupyter](./jupyter-overview.md) documentation for more! +## Quick Start +Use Jupyter notebook outputs as interactive figures in your Curvenote articles with automatic versioning and updates + +Curvenote is built to work hand in hand with Jupyter and allows you to directly use outputs from Jupyter as figures within your Curvenote articles. The versioning in Curvenote also allows for you to easily update your image in the article, rather than having to copy-and-paste a new static image each time you update your code. + +## Before You Start + +Make sure you have: +- A Jupyter notebook with outputs you want to use +- The notebook linked to your Curvenote project +- An article where you want to add the interactive outputs ## Video Demo 📺 -```{iframe} https://www.loom.com/embed/0c36c55d57644938825f5b7e05072f9f -:label: DFsqOymUMf -:align: center -:width: 100% -``` +[Watch the video tutorial](https://www.loom.com/embed/0c36c55d57644938825f5b7e05072f9f) + +## 1. Import Jupyter Outputs + +To use Jupyter outputs in your Curvenote articles: + +1. **Open your Jupyter notebook** in Curvenote +2. **Select the output cell** you want to use (chart, plot, visualization, etc.) +3. **Copy the output** using the copy button or keyboard shortcut +4. **Paste into your article** where you want the output to appear + +The output will appear as a figure in your article and maintain its connection to the original notebook. + +## 2. Format Outputs as Figures + +Once imported, you can format Jupyter outputs as interactive figures: + +1. **Select the output** in your article +2. **Use the formatting toolbar** that appears: + - Adjust size and location + - Add captions and numbering + - Set alignment and width +3. **The output becomes a figure** that can be referenced throughout your text + +## 3. Reference Interactive Figures + +You can reference interactive figures the same way as regular figures: + +### Method 1: Command Menu +- Type `/link to figure` in your text +- Select the interactive figure from the dropdown menu + +### Method 2: Keyboard Shortcut +- Type `[[fig:` in your text +- Select the interactive figure from the dropdown menu + +## 4. Update Interactive Outputs + +When you update your Jupyter notebook: + +1. **Save your notebook** with the new outputs +2. **The linked outputs in your article** will automatically update +3. **No manual copying/pasting** required - Curvenote handles the versioning + +This ensures your articles always show the latest results from your analysis. + +## 5. Use Interactive Features + +Interactive Jupyter outputs can include: + +- **Interactive plots** (Plotly, Bokeh, etc.) +- **Dynamic visualizations** that respond to user input +- **Embedded widgets** and controls +- **Live data displays** that update automatically + +## Next Steps + +- [Add Figures, Images, and Media →](./figures-and-images.md) +- [Link Data and Code →](./add-and-link-notebooks.md) +- [Write a Scientific Paper using Jupyter →](../authoring/jupyter-notebooks.md) + +--- -### Outputs as Figures +💡 **Tip:** Interactive outputs maintain their full functionality when embedded in Curvenote articles, allowing readers to explore your data and visualizations directly within the document. -Once you’ve imported your output cell into a Curvenote article, you can format the output as a figure. You can adjust the size and location, add a caption and numbering, and referencing the figure throughout your text. The formatting options are available in a toolbar that appears above or below the figure when you select the figure. Learn more about referencing figures [Internal References](./internal-references.md). +See [Interactive Outputs in Jupyter](./interactive-outputs-in-jupyter.md) for advanced features and [Jupyter Overview](./jupyter-overview.md) for more information!