diff --git a/Publish/editorial-process.md b/Publish/editorial-process.md
new file mode 100644
index 0000000..d2811fd
--- /dev/null
+++ b/Publish/editorial-process.md
@@ -0,0 +1,101 @@
+---
+title: Publishing Workflow
+short_title: Editorial Process
+---
+
+# Publishing Workflow
+
+## Quick Start
+Navigate the complete publishing workflow from submission to publication, including peer review, revisions, and final acceptance through Curvenote's collaborative platform
+
+## Before You Start
+- Ensure your article is complete and ready for submission
+- Have your author information and affiliations ready
+- Understand the journal's scope and requirements
+- Prepare for the peer review process
+
+## 1. Submit Your Article
+
+Submit your paper by creating a pull request to the journal's repository:
+
+- **Fork the repository** to your GitHub account
+- **Create a new branch** for your submission
+- **Add your manuscript** to the appropriate folder (e.g., `papers`)
+- **Open a pull request** to merge your branch into the main repository
+- **Include all required metadata** (authors, affiliations, abstract, DOIs)
+
+The pull request serves as the primary hub for discussion and review.
+
+## 2. Automated Checks and Preview
+
+Upon submission, automated checks verify your submission:
+
+- **Template compliance** - Ensures adherence to journal formatting
+- **Metadata validation** - Checks for required author information
+- **Reference verification** - Validates DOI inclusion in citations
+- **Preview generation** - Creates a live preview accessible via GitHub comment
+
+Address any failed checks before proceeding to review.
+
+## 3. Editorial Assignment
+
+An editor is assigned to oversee your submission:
+
+- **Scope assessment** - Editor evaluates if your topic fits the journal
+- **Quality review** - Initial evaluation of submission completeness
+- **Process guidance** - Editor explains next steps and timeline
+- **Reviewer selection** - Editor identifies appropriate peer reviewers
+
+## 4. Peer Review Process
+
+Reviewers provide feedback through the GitHub pull request:
+
+- **Expert evaluation** - Subject matter experts assess your work
+- **Public discussion** - All feedback is visible and transparent
+- **Inline comments** - Specific suggestions for improvements
+- **General feedback** - Overall assessment and recommendations
+
+Reviewers are tagged (`@username`) for notifications and communication.
+
+## 5. Author Revisions
+
+Respond to reviewer feedback with revisions:
+
+- **Address comments** - Make changes based on reviewer suggestions
+- **Update pull request** - Add new commits with your revisions
+- **Explain changes** - Provide context for major modifications
+- **Iterate as needed** - Multiple revision cycles may be required
+
+## 6. Final Decision and Acceptance
+
+The editor makes the final decision:
+
+- **Reviewer satisfaction** - All reviewers must approve the final version
+- **Editor approval** - Assigned editor reviews final submission
+- **Merge to main** - Pull request is merged, indicating acceptance
+- **Publication preparation** - Article moves to publication phase
+
+## 7. Publication and Distribution
+
+Your accepted article becomes publicly available:
+
+- **Curvenote publication** - Article is published on the platform
+- **DOI assignment** - Permanent identifier is assigned
+- **Journal listing** - Article appears on the journal's website
+- **Community announcement** - Publication is shared through appropriate channels
+
+## Next Steps
+- Learn about [Managing Authors and Contributors](editor/authors.md)
+- Understand [Export Options](editor/export-pdf.md)
+- Explore [Site Configuration](site-design/layout-and-theme.md)
+- Review [Citation Management](authoring/citations.md)
+
+---
+
+💡 **Tip:** Keep all communication professional and constructive. The transparent review process benefits the entire community by sharing knowledge and improving research quality.
+
+⚡ **Important: Publishing Best Practices**
+- Respond promptly to reviewer comments
+- Be open to constructive criticism
+- Maintain clear communication with editors
+- Follow the journal's specific guidelines and formatting requirements
diff --git a/Publish/export-pdf-typst.md b/Publish/export-pdf-typst.md
new file mode 100644
index 0000000..76d94f1
--- /dev/null
+++ b/Publish/export-pdf-typst.md
@@ -0,0 +1,380 @@
+---
+title: Export Your Scientific Paper to PDF and Typst
+short_title: Export to PDF/Typst
+description: Step-by-step tutorial for exporting your Curvenote scientific papers to professional PDF and Typst formats
+---
+
+# Export Your Scientific Paper to PDF and Typst
+
+## Quick Start
+Export your Curvenote scientific papers to professional PDF and Typst formats for submission to journals, preprint servers, or sharing with collaborators
+
+This tutorial guides you through exporting your scientific papers from Curvenote to both PDF and Typst formats. Whether you're submitting to a journal, uploading to a preprint server, or sharing with colleagues, this tutorial covers the complete export workflow for both formats.
+
+## Before You Start
+
+Make sure you have:
+- A completed scientific paper in Curvenote
+- Your paper saved as a version (not in draft mode)
+- Author information and affiliations ready
+- Target journal or publication venue requirements
+- Curvenote CLI installed (for advanced export options)
+
+## 1. Choose Your Export Format
+
+### PDF Export
+**Best for**: Journal submissions, preprint servers, final publications, sharing with non-technical audiences
+
+**Advantages**:
+- Universal compatibility
+- Fixed formatting
+- Professional appearance
+- Widely accepted by journals
+
+### Typst Export
+**Best for**: Modern publishing workflows, fast compilation, clean source files, version control
+
+**Advantages**:
+- Fast compilation
+- Clean, readable source code
+- Modern syntax
+- Excellent for version control
+
+## 2. Prepare Your Paper for Export
+
+### Save Your Work
+1. **Exit draft mode** - Click "STOP EDITING" in the article header
+2. **Save your version** - Click "SAVE VERSION" to include all changes
+3. **Verify content** - Check that all figures, citations, and formatting are correct
+4. **Review metadata** - Ensure author information and affiliations are complete
+
+```{important}
+Only saved versions can be exported. Draft mode changes are not included unless you save a version.
+```
+
+### Check Your Content
+- **Figures and images** are properly formatted and captioned
+- **Citations and references** are complete and properly linked
+- **Mathematical equations** render correctly
+- **Tables and data** are properly formatted
+- **Cross-references** work correctly
+
+## 3. Export to PDF
+
+### Web-Based Export (Recommended for most users)
+
+#### Step 1: Access Export Options
+1. **Navigate to your article** in Curvenote
+2. **Click the download icon** (⬇) in the article header
+3. **Select "Export As"** from the dropdown menu
+4. **Choose "PDF" format** and click "Next"
+
+#### Step 2: Select a Template
+1. **Browse available templates** - View thumbnails of different layouts
+2. **Preview templates** - Hover over thumbnails for expanded previews
+3. **Consider your audience** - Select templates appropriate for your publication venue
+4. **Click "Select"** on your chosen template
+
+**Popular templates**:
+- **Default**: Clean, professional layout
+- **Nature**: Journal-specific formatting
+- **Science**: Academic journal style
+- **IEEE**: Technical conference format
+- **ACM**: Computer science journal style
+
+#### Step 3: Configure Template Options
+1. **Fill in required fields**:
+   - Author name and affiliation
+   - Email address
+   - Abstract (if using tagged blocks)
+   - Acknowledgments (if applicable)
+
+2. **Optional settings**:
+   - Additional metadata
+   - Custom formatting options
+   - Special requirements
+
+3. **Click "Next"** to proceed
+
+#### Step 4: Export and Download
+1. **Click "EXPORT"** to start the process
+2. **Wait for processing** - The system generates your PDF
+3. **Monitor progress** - You can exit the window during processing
+4. **Download your PDF**:
+   - From export popup: Click the cloud download icon (☁️⬇️)
+   - From article header: Click download icon and select "Download PDF"
+
+### CLI-Based Export (Advanced users)
+
+#### Install Dependencies
+```bash
+# Install jtex for LaTeX/PDF export
+pip install jtex
+
+# Install LaTeX distribution (if not already installed)
+# For Ubuntu/Debian
+sudo apt-get install texlive-full
+
+# For macOS
+brew install --cask mactex
+
+# For Windows
+# Download and install MiKTeX from https://miktex.org/
+```
+
+#### Export Command
+```bash
+# Basic PDF export
+curvenote export pdf
+
+# Export with specific template
+curvenote export pdf --template nature
+
+# Export with custom output name
+curvenote export pdf --output my_paper.pdf
+
+# Export specific version
+curvenote export pdf --version v1.2
+```
+
+#### Generated Files
+```
+my-curvenote-pdf/
+├── _build/
+│   ├── main.tex
+│   ├── class_file.cls
+│   ├── images/
+│   └── other files...
+├── main.pdf
+└── main.log
+```
+
+## 4. Export to Typst
+
+### CLI-Based Export (Typst requires CLI)
+
+#### Install Typst Compiler
+```bash
+# Using Cargo (Rust package manager)
+cargo install typst-cli
+
+# For macOS (using Homebrew)
+brew install typst
+
+# For Windows (using Chocolatey)
+choco install typst
+
+# For Ubuntu/Debian
+curl -L https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-gnu.tar.gz | tar xz
+sudo mv typst /usr/local/bin/
+```
+
+#### Export Command
+```bash
+# Basic Typst export
+curvenote export typst
+
+# Export with specific template
+curvenote export typst --template article
+
+# Export with custom output name
+curvenote export typst --output my_paper.typ
+
+# Export specific version
+curvenote export typst --version v1.2
+```
+
+#### Compile Typst to PDF
+```bash
+# Compile the exported Typst file
+typst compile my_paper.typ
+
+# Compile with specific output
+typst compile my_paper.typ --output my_paper.pdf
+
+# Watch for changes (development mode)
+typst watch my_paper.typ
+```
+
+#### Generated Files
+```
+my-curvenote-typst/
+├── main.typ
+├── references.bib
+├── figures/
+└── main.pdf (after compilation)
+```
+
+## 5. Configure Export Settings
+
+### Project Configuration
+Create or update `curvenote.yml` in your project:
+
+```yaml
+project:
+  title: "My Scientific Paper"
+  description: "Research paper for journal submission"
+  
+  # PDF export settings
+  export:
+    pdf:
+      template: nature
+      bibliography: references.bib
+      figures: true
+      tables: true
+      
+    # Typst export settings
+    typst:
+      template: article
+      bibliography: references.bib
+      figures: true
+      tables: true
+      
+  # Bibliography settings
+  bibliography:
+    - references.bib
+```
+
+### Template Customization
+For advanced users, you can customize templates:
+
+```yaml
+project:
+  export:
+    pdf:
+      template: custom-nature
+      template-path: ./templates/
+      
+    typst:
+      template: custom-article
+      template-path: ./templates/
+```
+
+## 6. Handle Common Export Issues
+
+### PDF Export Issues
+
+#### Missing Dependencies
+```bash
+# Install required LaTeX packages
+tlmgr install amsmath amssymb geometry hyperref natbib
+tlmgr install graphics graphicx subcaption booktabs
+```
+
+#### Template Not Found
+```bash
+# List available templates
+curvenote templates list
+
+# Use default template
+curvenote export pdf --template default
+```
+
+#### Bibliography Issues
+```bash
+# Ensure BibTeX file is in project
+# Check bibliography path in curvenote.yml
+# Verify citation keys match BibTeX entries
+```
+
+### Typst Export Issues
+
+#### Compilation Errors
+```bash
+# Check Typst syntax
+typst compile --diagnostic-format=human my_paper.typ
+
+# Verify Typst installation
+typst --version
+```
+
+#### Missing Fonts
+```bash
+# Install additional fonts
+# Typst includes many fonts by default
+# Check font availability in your system
+```
+
+#### Template Compatibility
+```bash
+# Use basic template for compatibility
+curvenote export typst --template basic
+
+# Check template requirements
+# Some templates may require specific Typst versions
+```
+
+## 7. Best Practices
+
+### Before Export
+- **Review your content** thoroughly
+- **Test with different templates** to find the best fit
+- **Check journal requirements** for formatting
+- **Verify all citations** are properly formatted
+- **Ensure figures** are high quality and properly captioned
+
+### During Export
+- **Use appropriate templates** for your target venue
+- **Fill in all required metadata** completely
+- **Test export with sample content** first
+- **Keep export logs** for troubleshooting
+
+### After Export
+- **Review the exported document** carefully
+- **Check formatting** matches requirements
+- **Verify all content** is included correctly
+- **Test file compatibility** with target systems
+- **Backup exported files** for future reference
+
+### Format-Specific Tips
+
+#### PDF Best Practices
+- **Use vector graphics** for figures when possible
+- **Embed fonts** if required by journal
+- **Check page limits** and formatting requirements
+- **Verify PDF/A compliance** if required
+
+#### Typst Best Practices
+- **Use Typst's modern syntax** for better maintainability
+- **Leverage fast compilation** for iterative development
+- **Keep source files** for version control
+- **Use Typst's template system** for consistency
+
+## 8. Submit to Journals and Preprint Servers
+
+### Journal Submission
+1. **Check journal requirements** for file format and template
+2. **Export with appropriate template** (Nature, Science, etc.)
+3. **Review formatting** against journal guidelines
+4. **Submit PDF or source files** as required
+
+### Preprint Servers
+1. **Choose appropriate server** (arXiv, bioRxiv, etc.)
+2. **Export to required format** (usually PDF)
+3. **Check file size limits** and compression requirements
+4. **Upload and verify** submission
+
+### Collaboration Sharing
+1. **Export to universal format** (PDF for most users)
+2. **Include source files** (Typst) for collaborators who can edit
+3. **Use version control** for tracking changes
+4. **Share via appropriate channels** (email, cloud storage, etc.)
+
+## Next Steps
+
+- [Learn about Export Templates →](../Publish/export-template-options.md)
+- [Understand Tagging Blocks →](../Publish/export-tagging-blocks.md)
+- [Explore CLI Export Options →](../cli/export.md)
+- [Review Publishing Workflow →](../publishing/editorial-process.md)
+
+---
+
+💡 **Tip:** Export a test version with your chosen template before finalizing your paper to ensure the formatting meets your requirements.
+
+⚡ **Important: Export Best Practices**
+
+- **Always save versions** before exporting
+- **Test with sample content** first
+- **Keep export logs** for troubleshooting
+- **Verify formatting** against target requirements
+- **Backup exported files** for future reference
diff --git a/Publish/export-pdf.md b/Publish/export-pdf.md
new file mode 100644
index 0000000..df0cb21
--- /dev/null
+++ b/Publish/export-pdf.md
@@ -0,0 +1,106 @@
+---
+title: Export Articles as PDF
+short_title: PDF Export
+description: Export and download your Curvenote articles as professional PDF documents using customizable templates
+---
+
+# Export Articles as PDF
+
+## Quick Start
+Export your Curvenote articles as professional PDF documents with customizable templates, proper formatting, and publication-ready output
+
+## Before You Start
+- Ensure your article is complete and ready for export
+- Exit draft mode and save your latest version
+- Have your author information and affiliations ready
+- Choose an appropriate template for your content
+
+## 1. Prepare Your Article for Export
+
+Before exporting, ensure your article is in the correct state:
+
+- **Exit draft mode** - Click "STOP EDITING" in the header to return to the last saved version
+- **Save your version** - Click "SAVE VERSION" to include draft changes in the export
+- **Verify content** - Check that all figures, citations, and formatting are correct
+- **Review metadata** - Ensure author information and affiliations are complete
+
+Only saved versions can be exported - draft mode changes are not included unless you save a version.
+
+## 2. Access the Export Function
+
+Navigate to the export options:
+
+- **Click the download icon** (⬇) in the article header
+- **Select "Export As"** from the dropdown menu
+- **Choose "PDF" format** and click "Next"
+- **Verify permissions** - Only owners or collaborators can download articles
+
+## 3. Select a Template
+
+Choose from professional PDF templates:
+
+- **Browse templates** - View thumbnails of available layouts
+- **Preview templates** - Hover over thumbnails for expanded previews
+- **Consider your audience** - Select templates appropriate for your publication venue
+- **Click "Select"** on your chosen template
+
+Each template has different layouts and formatting options.
+
+## 4. Configure Template Options
+
+Complete the template-specific configuration:
+
+- **Required fields** - Fill in author name, affiliation, email, etc.
+- **Optional settings** - Configure additional metadata as needed
+- **Content tagging** - Use tagged blocks for abstracts and acknowledgements
+- **Click "Next"** to proceed to export
+
+Template options vary by template - follow the specific instructions for your chosen template.
+
+## 5. Export and Process
+
+Generate your PDF document:
+
+- **Click "EXPORT"** to start the process
+- **Wait for processing** - The system generates your PDF
+- **Monitor progress** - You can exit the window during processing
+- **Receive notification** - You'll be notified when export is complete
+
+Processing time depends on article length and complexity.
+
+## 6. Download Your PDF
+
+Retrieve your exported document:
+
+- **From export popup** - Click the cloud download icon (☁️⬇️)
+- **From article header** - Click download icon and select "Download PDF"
+- **Access log file** - Download the export log for troubleshooting
+- **Share with collaborators** - Exported PDFs are available to all collaborators
+
+Exported PDFs remain available until you save a new version.
+
+## 7. Manage Multiple Exports
+
+Handle different versions and formats:
+
+- **Version-specific exports** - Each saved version requires a new export
+- **Template variations** - Export the same content with different templates
+- **Collaborative access** - All collaborators can download exported PDFs
+- **Archive exports** - Keep exported files for reference and sharing
+
+## Next Steps
+- Learn about [Export Template Options](export-template-options.md)
+- Understand [Tagging Blocks for Export](export-tagging-blocks.md)
+- Explore [Other Export Formats](cli/export.md)
+- Review [Publishing Workflow](publishing/editorial-process.md)
+
+---
+
+💡 **Tip:** Export a test version with your chosen template before finalizing your article to ensure the formatting meets your requirements.
+
+⚡ **Important: PDF Export Best Practices**
+- Always save your version before exporting to include latest changes
+- Choose templates that match your target publication venue
+- Verify all figures and citations render correctly in the PDF
+- Test the export process early in your workflow to avoid last-minute issues
+- Keep exported PDFs for backup and sharing purposes
diff --git a/authoring/authors.md b/authoring/authors.md
new file mode 100644
index 0000000..8250045
--- /dev/null
+++ b/authoring/authors.md
@@ -0,0 +1,164 @@
+---
+title: Manage Authors and Contributors
+short_title: Authors
+---
+
+# Manage Authors and Contributors
+
+## Quick Start
+Add, edit, and manage authors for your Curvenote articles with full metadata including ORCID, affiliations, and contributor roles
+
+Manage authors and contributors for your articles with comprehensive metadata support. Add multiple authors, set affiliations, assign contributor roles, and ensure proper attribution for all contributors to your work.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote article open in the editor
+- Access to edit mode for the article
+- Author information ready (names, ORCID, affiliations)
+- Understanding of contributor roles if needed
+
+## 1. Access Author Management
+
+Open the author management interface:
+
+**Enter Edit Mode**: Click **EDIT** at the top of the page
+
+**Click on Author List**: Click anywhere on the existing author list
+
+**Author Panel Opens**: The author management interface appears
+
+**Add New Author**: Click **+ Add Author** to begin
+
+## 2. Add New Authors
+
+Add authors to your article:
+
+**Search for Existing Users**:
+- Type username or email in search field
+- Select from dropdown results
+- Author profile loads automatically
+
+**Create New Author**:
+- Click "Create new author"
+- Enter author information manually
+- Fill in required fields
+
+**Required Information**:
+- **Name**: Full author name
+- **Email**: Contact email address
+- **ORCID**: Researcher identifier (optional but recommended)
+
+## 3. Set Author Metadata
+
+Configure detailed author information:
+
+**ORCID ID**: Enter researcher identifier for proper attribution
+
+**Corresponding Author**: Mark primary contact author
+
+**Email Address**: Set contact email for correspondence
+
+**Affiliations**: Add institutional affiliations
+
+**Contributor Roles**: Assign CRediT roles for contributions
+
+## 4. Manage Affiliations
+
+Set up and manage institutional affiliations:
+
+**Add Affiliations**:
+- Click "Edit Affiliations" button
+- Search for existing institutions
+- Create new affiliations if needed
+
+**Multiple Affiliations**:
+- Use arrow keys to navigate
+- Type to search for additional affiliations
+- Select multiple institutions per author
+
+**Edit Existing Affiliations**:
+- Click on affiliation name
+- Modify institution details
+- Save changes to project
+
+## 5. Assign Contributor Roles
+
+Use CRediT roles for detailed attribution:
+
+**Available Roles**:
+- **Conceptualization**: Ideas and research direction
+- **Data curation**: Data management and organization
+- **Formal analysis**: Statistical analysis and modeling
+- **Funding acquisition**: Securing financial support
+- **Investigation**: Conducting experiments and research
+- **Methodology**: Development of research methods
+- **Project administration**: Project coordination
+- **Resources**: Providing materials and tools
+- **Software**: Software development and programming
+- **Supervision**: Oversight and leadership
+- **Validation**: Verification of results
+- **Visualization**: Creating figures and graphics
+- **Writing**: Original draft and revisions
+
+## 6. Reorder and Remove Authors
+
+Manage author order and remove contributors:
+
+**Change Author Order**:
+- Drag and drop authors in list
+- Author order affects publication order
+- First author is typically lead contributor
+
+**Remove Authors**:
+- Click author name in list
+- Select "Remove Author" option
+- Confirm removal action
+
+**⚠️ Important**: Removing authors doesn't affect project collaborators
+
+## 7. Troubleshoot Common Issues
+
+Resolve frequent author management problems:
+
+**Can't Add Second Author**:
+- Ensure you're in Edit Mode
+- Click on existing author list
+- Use "+ Add Author" button
+- Check user permissions
+
+**Author Not Found in Search**:
+- Verify username spelling
+- Try email address instead
+- Create new author profile
+- Check if user exists on Curvenote
+
+**Affiliations Not Saving**:
+- Click "Edit Affiliations" button
+- Save changes before closing
+- Check for required fields
+- Verify project permissions
+
+**ORCID Not Linking**:
+- Verify ORCID format (0000-0000-0000-0000)
+- Check ORCID is valid and public
+- Try refreshing the page
+- Contact support if persistent
+
+## Next Steps
+
+- [Collaborate with Teams →](./collaboration.md)
+- [Manage Project Settings →](./curvenote-projects.md)
+- [Export Your Article →](./export-pdf.md)
+
+---
+
+💡 **Tip:** Use ORCID IDs whenever possible to ensure proper attribution and avoid author name confusion across publications.
+
+⚡ **Important: Author Management Best Practices**
+
+- **Use ORCID IDs**: Link authors to their ORCID for proper attribution
+- **Set corresponding author**: Mark the primary contact for the article
+- **Assign contributor roles**: Use CRediT roles for detailed attribution
+- **Verify affiliations**: Ensure institutional affiliations are accurate
+- **Check author order**: Confirm author order matches contribution level
diff --git a/authoring/citations.md b/authoring/citations.md
new file mode 100644
index 0000000..2b799ce
--- /dev/null
+++ b/authoring/citations.md
@@ -0,0 +1,167 @@
+---
+title: Add Citations and References
+short_title: Citations
+---
+
+# Add Citations and References
+
+## Quick Start
+Add academic citations and references to your Curvenote articles using DOIs or BibTeX files, with easy access through the citation menu
+
+Curvenote supports two main methods for adding citations: searching by DOI for individual papers, or importing BibTeX files from reference managers. Once added, citations are stored in your project library and can be easily inserted and managed throughout your content.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content you want to cite
+- DOIs for papers you want to reference, or BibTeX files from your reference manager
+- Access to the Curvenote editor interface
+- Your reference manager set up (Zotero, Mendeley, etc.) if using BibTeX import
+
+## 1. Add Citations Using DOIs
+
+Add individual papers by searching their DOI:
+
+### Locate the DOI
+- Find the DOI on the article or document you want to cite
+- Copy the DOI to your clipboard
+
+```{note}
+The DOI is usually included with the article content. If you cannot find the DOI, you can use the 'Search Metadata' option on [crossref.org](https://crossref.org).
+```
+
+### Add the Citation
+1. **Place your cursor** where you want to add the citation
+2. **Access the citation menu** using the `/cite` command
+3. **Navigate to ADD DOI**
+4. **Enter the DOI** in the search bar
+5. **Select SEARCH**
+6. **Choose CREATE CITATION** if the correct article appears
+
+```{figure} images/MshxlXndaLsk3WbJ0ZGy-tZmadZXYnXoMbmz0nAwm-v2.mp4
+:name: 17800507
+:align: center
+:width: 70%
+```
+
+## 2. Import Citations from BibTeX Files
+
+Import multiple references from your reference manager:
+
+### Export BibTeX File
+- Export your references as a BibTeX file from your reference manager
+- Common reference managers: Zotero, Mendeley, EndNote
+- For easy access without downloads, use [zbib.org](https://zbib.org/)
+
+### Import to Curvenote
+1. **Drag and drop** the BibTeX file into Curvenote
+2. **All references** will be added to your project library
+3. **Citation keys** are automatically generated from your BibTeX entries
+
+```{figure} images/MshxlXndaLsk3WbJ0ZGy-RaR3QGIKD1ek3VXMAX31-v3.mp4
+:name: adaa6acf
+:align: center
+:width: 70%
+
+Import your references from a `*.bib` file, and easily update your references if you need to!
+```
+
+## 3. Insert Citations in Your Content
+
+Add citations to your articles using the citation menu:
+
+### Single Citation
+1. **Place your cursor** where you want the citation
+2. **Use the `/cite` command** to open the citation menu
+3. **Search for your reference** by title, author, or citation key
+4. **Select the citation** to insert it
+
+### Multiple Citations
+1. **Place your cursor** where you want the citations
+2. **Use the `/reference` command** to open the references menu
+3. **Filter using Search** and select multiple citations with checkboxes
+4. **Choose INSERT CITATIONS** to add them all
+
+```{figure} images/MshxlXndaLsk3WbJ0ZGy-V58UiaFTTyA5qx1tti7D-v1.png
+:name: bb7026ea
+:align: center
+:width: 60%
+```
+
+## 4. Manage and Rearrange Citations
+
+Organize your citations and adjust their formatting:
+
+### Citation Groups
+- **Individual citations** are added by default when using `[[cite:`
+- **Group citations** using the `[]` icon in the toolbar
+- **Drag citations** into and out of citation groups
+- **Multiple citations** added via `/reference` are automatically grouped
+
+### Citation Formatting
+- **Parenthetical citations**: `{cite:p}` for (Author, Year) format
+- **Narrative citations**: `{cite:t}` for "Author (Year)" format
+- **Toggle brackets** using the `[]` button when citation is selected
+
+```{figure} images/MshxlXndaLsk3WbJ0ZGy-jTbSRxmzUrpQhHBo3ZuF-v3.mp4
+:name: a25010aa
+:align: center
+:width: 70%
+
+Use the `[]` button to toggle the brackets around the citation. You can drag citations into different groups, or rearrange them in order.
+```
+
+## Citation Examples
+
+```{list-table} Example of rendered citations, try clicking on any of the citations!
+:header-rows: 1
+:name: jBqbQidSUR
+
+* -
+
+  - Parenthetical citation
+
+  - Narrative citation
+
+* - 1 author
+
+  - {cite:p}`heinen_compensation_2014`
+
+  - {cite:t}`heinen_compensation_2014`
+
+* - 2 authors
+
+  - {cite:p}`Bartkowski2018Leverage`
+
+  - {cite:t}`Bartkowski2018Leverage`
+
+* - 3 or more authors
+
+  - {cite:p}`winter_effects_2018`
+
+  - {cite:t}`winter_effects_2018`
+
+* - Group author
+
+  - {cite:p}`EuropeanCommission2020`
+
+  - {cite:t}`EuropeanCommission2020`
+
+```
+
+## Next Steps
+
+- [Add Figures and Media →](./add-figures-media.md)
+- [Link Data and Code →](./link-data-code.md)
+- [Organize Your Content →](./organize-content.md)
+
+---
+
+💡 **Tip:** Use the `/cite` command for quick access to your citation library. You can search by title, author, or citation key to find references quickly.
+
+⚡ **Important: Citation Management**
+
+- **Update citations** by re-exporting BibTeX with the same citation keys
+- **Citation keys** are automatically generated as `ref-` + lowercase citation key
+- **Click on citations** to view details and navigate to the original source
+- **Citation groups** correspond to LaTeX `\citep{}` format for proper academic styling
diff --git a/authoring/figures-and-images.md b/authoring/figures-and-images.md
new file mode 100644
index 0000000..654c24e
--- /dev/null
+++ b/authoring/figures-and-images.md
@@ -0,0 +1,149 @@
+---
+title: Add Figures, Images, and Media
+short_title: Figures & Images
+---
+
+# Add Figures, Images, and Media
+
+## Quick Start
+Add images, GIFs, and other media to your Curvenote articles using drag-and-drop or copy-paste methods
+
+Curvenote supports various image formats (JPEG, TIFF, PNG, etc.) and GIFs that can be added to content blocks or displayed as standalone figures. Once added, images can be formatted, resized, and given numbered captions for easy referencing throughout your document.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content you want to add images to
+- Images or GIFs ready to upload from your computer
+- Access to the Curvenote editor interface
+- Images in supported formats (JPEG, TIFF, PNG, GIF)
+
+## 1. Add Images to Content Blocks
+
+Insert images directly into existing content:
+
+### Enter Draft Mode
+1. **Click EDIT** at the top of the page to enter Draft Mode
+2. **Double-click** within the content block or select it and press `enter`
+
+### Add Your Image
+Choose one of these methods:
+
+**Drag and Drop:**
+- **Drag images** from your computer directly into the content block
+- **A line appears** as you drag, showing where the image will be placed
+- **Drop the image** and it appears below that line
+
+**Copy and Paste:**
+- **Copy an image** from your clipboard
+- **Paste it** directly into the content block
+
+**Command Menu:**
+1. **Open the command menu** by typing `/`
+2. **Search for "image"**
+3. **Drag and drop** images into the upload box or click to browse files
+
+**Insert Menu:**
+1. **Click the insert menu** in the editing toolbar
+2. **Select "Image"**
+3. **Drag and drop** images or click to browse files
+
+## 2. Create Standalone Image Blocks
+
+Display images as their own content blocks:
+
+### Prepare the Page
+1. **Enter Draft Mode** by clicking **EDIT** at the top of the page
+2. **Select the block** above where you want to add your image
+3. **Press `esc`** until the entire block is selected or click the block selection tab
+
+### Add the Image
+1. **Paste your image** from clipboard
+2. **A new block appears** below containing just your image
+3. **The image is now** a standalone block that can be moved or formatted independently
+
+## 3. Format and Style Images
+
+Adjust the appearance and layout of your images:
+
+### Formatting Toolbar
+Once an image is uploaded, you'll see a formatting toolbar with options to:
+- **Adjust alignment** (left, center, right)
+- **Change width** (percentage or pixels)
+- **Delete the image** if needed
+
+### Image Settings
+Access detailed settings for your images:
+
+**For images in content blocks:**
+1. **Click the ⋮ Options menu** to the top-right of the image
+2. **Select "Image Settings"**
+
+**For standalone image blocks:**
+1. **Click the ⋮ Options menu** to the top-right of the block
+2. **Select "Block Settings"**
+
+**Available settings:**
+- **URL**: Direct link to the image
+- **Title**: Internal title for the image
+- **Description**: Hidden description for organization
+- **Image Caption**: Visible caption displayed below the image
+- **Tags**: Organizational tags for the image
+
+## 4. Create Numbered Figures
+
+Format images as figures with captions and numbering:
+
+### Enable Figure Formatting
+1. **Select the image** you want to format as a figure
+2. **In the formatting toolbar:**
+   - **Click the lines symbol** to show/hide the caption
+   - **Click the number icon** to toggle numbering (when caption is shown)
+
+### Reference Figures
+Link to figures throughout your content:
+
+**Using commands:**
+- **Type `/link to figure`** and select from the dropdown
+- **Type `[[fig:`** and select from the dropdown
+
+**When you click on a reference:**
+- **A preview appears** showing the image and its caption
+- **Easy navigation** between figure references
+
+```{note}
+Figure numbering is ordered by location on the page, starting at 1. Numbers automatically update when figures are added or removed.
+```
+
+## 5. Manage Image Versions
+
+Track and manage different versions of your images:
+
+### Replace Images
+1. **Select the image** you want to replace
+2. **Drag and drop** or paste a new image onto the existing one
+3. **A new version** is automatically created
+
+### Access Previous Versions
+1. **Select the image**
+2. **Expand the Block Details Panel** on the right side
+3. **Select a version** to preview it
+4. **Click "USE VERSION"** to switch to that version
+
+## Next Steps
+
+- [Add Interactive Figures →](../authoring/interactive-figures.md)
+- [Link Data and Code →](../authoring/link-data-code.md)
+- [Organize Your Content →](../authoring/organize-content.md)
+
+---
+
+💡 **Tip:** Use the drag-and-drop method for quick image uploads. You can add multiple images at once by selecting multiple files and dragging them together.
+
+⚡ **Important: Image Best Practices**
+
+- **Supported formats**: JPEG, TIFF, PNG, GIF for best compatibility
+- **File size**: Keep images under 10MB for optimal performance
+- **Captions**: Always add descriptive captions to figures for accessibility
+- **References**: Use figure references to link to images throughout your content
+- **Versioning**: Images are automatically versioned when replaced, preserving your history
diff --git a/authoring/jupyter-notebooks.md b/authoring/jupyter-notebooks.md
index 515e6af..31878a3 100644
--- a/authoring/jupyter-notebooks.md
+++ b/authoring/jupyter-notebooks.md
@@ -3,159 +3,434 @@ title: Write a Scientific Paper using Jupyter
 short_title: Write using Jupyter
 ---
 
-# Write a Scientific Paper using Jupyter
+# Writing a Scientific Paper using Jupyter
 
 ## Quick Start
-Create scientific papers directly from Jupyter notebooks with integrated code, outputs, and narrative text
+Create publication-quality scientific papers using Jupyter notebooks with Curvenote, combining code execution, interactive outputs, and rich documentation
 
-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.
+Jupyter notebooks (`.ipynb` files) are perfect for scientific papers that include computational work, data analysis, or interactive visualizations. Curvenote provides first-class support for Jupyter notebooks, allowing you to create documents that combine executable code, interactive outputs, and publication-quality documentation seamlessly.
 
 ## 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
+- A Curvenote project to write your paper in
+- Jupyter environment installed (JupyterLab or Jupyter Notebook)
+- Python or other programming language set up
+- Data files or computational resources ready
+- Access to the Curvenote editor interface
 
 ## 1. Set Up Your Jupyter Environment
 
-Start with a well-organized Jupyter notebook:
+Install and configure Jupyter for scientific writing:
 
-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
+### Install Jupyter
+```bash
+# Install JupyterLab (recommended)
+pip install jupyterlab
 
-## 2. Structure Your Paper
+# Or install classic Jupyter Notebook
+pip install notebook
+```
+
+### Start Jupyter
+```bash
+# Start JupyterLab
+jupyter lab
+
+# Or start classic Jupyter Notebook
+jupyter notebook
+```
+
+### Install Scientific Libraries
+```bash
+# Common scientific Python packages
+pip install pandas numpy matplotlib seaborn plotly altair
+```
+
+## 2. Structure Your Scientific Paper
+
+Organize your notebook with clear sections using Markdown cells:
+
+### Create Paper Sections
+```{myst}
+# Title of Your Scientific Paper
+
+## Abstract
+
+Brief summary of your research question, methods, and key findings.
+
+## Introduction
+
+Background information, research objectives, and significance of your work.
+
+## Methods
+
+Detailed description of your computational approach, data sources, and analysis methods.
+
+## Results
+
+Presentation of your findings with interactive visualizations and statistical analysis.
+
+## Discussion
 
-Organize your notebook to follow scientific paper conventions:
+Interpretation of results, implications, and future research directions.
 
-### Introduction Section
-- **Background and context** in markdown cells
-- **Literature review** with citations
-- **Research questions** and objectives
-- **Hypotheses** to be tested
+## References
 
-### Methods Section
-- **Data collection** procedures
-- **Code for data preprocessing**
-- **Analysis methods** with clear comments
-- **Statistical approaches** used
+Citations and bibliography using academic reference formats.
+```
+
+### Use Markdown for Narrative
+```{myst}
+## Data Analysis
+
+We analyzed the experimental dataset using Python's pandas library. Previous work by @smith2023 showed similar patterns in the data.
 
-### Results Section
-- **Code for analysis** with outputs
-- **Figures and visualizations**
-- **Statistical results** and tables
-- **Key findings** in markdown
+The analysis revealed three key findings:
 
-### Discussion Section
-- **Interpretation** of results
-- **Comparison** with previous work
-- **Limitations** and future work
-- **Conclusions** and implications
+1. **Finding 1**: Description of the first significant result
+2. **Finding 2**: Description of the second significant result  
+3. **Finding 3**: Description of the third significant result
+
+See {numref}`Figure %s <fig:results>` for a visualization of our results.
+```
 
-## 3. Add Rich Content
+## 3. Write and Execute Code Cells
 
-Enhance your paper with various content types:
+Add computational content to your scientific paper:
 
-### Code and Analysis
-```python
-# Example analysis code
+### Data Loading and Preprocessing
+```{code-cell} python
 import pandas as pd
+import numpy as np
 import matplotlib.pyplot as plt
+import seaborn as sns
 
-# Load and process data
+# Load experimental 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')
+# Basic data exploration
+print(f"Dataset shape: {data.shape}")
+print(f"Columns: {list(data.columns)}")
+print("\nFirst few rows:")
+print(data.head())
+```
+
+### Statistical Analysis
+```{code-cell} python
+# Perform statistical analysis
+results = data.groupby('condition').agg({
+    'value': ['mean', 'std', 'count', 'min', 'max']
+}).round(3)
+
+print("Statistical Summary by Condition:")
+print(results)
+
+# Calculate confidence intervals
+from scipy import stats
+confidence_intervals = data.groupby('condition')['value'].apply(
+    lambda x: stats.t.interval(0.95, len(x)-1, loc=x.mean(), scale=stats.sem(x))
+)
+print(f"\n95% Confidence Intervals: {confidence_intervals}")
+```
+
+### Create Publication-Quality Plots
+```{code-cell} python
+# Set up publication-quality plotting
+plt.style.use('seaborn-v0_8-whitegrid')
+fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+
+# Plot 1: Box plot
+sns.boxplot(data=data, x='condition', y='value', ax=ax1)
+ax1.set_title('Distribution by Condition')
+ax1.set_xlabel('Experimental Condition')
+ax1.set_ylabel('Measured Value')
+
+# Plot 2: Scatter plot
+sns.scatterplot(data=data, x='time', y='value', hue='condition', ax=ax2)
+ax2.set_title('Value Over Time')
+ax2.set_xlabel('Time (minutes)')
+ax2.set_ylabel('Measured Value')
+
+plt.tight_layout()
 plt.show()
 ```
 
-### Narrative Text
-Use markdown cells for:
-- **Explanations** of methods and results
-- **Citations** and references
-- **Context** and background information
-- **Discussion** of implications
+## 4. Add Interactive Visualizations
 
-### Interactive Elements
-- **Interactive plots** (Plotly, Bokeh)
-- **Data tables** with sorting/filtering
-- **Embedded widgets** for exploration
-- **Dynamic visualizations**
+Create engaging interactive plots that remain functional in Curvenote:
 
-## 4. Link to Curvenote
+### Interactive Scatter Plots
+```{code-cell} python
+import plotly.express as px
 
-Connect your Jupyter notebook to Curvenote:
+# Create interactive scatter plot
+fig = px.scatter(data, x='x_value', y='y_value', 
+                 color='category', size='magnitude',
+                 hover_data=['condition', 'time'],
+                 title='Interactive Results Visualization')
 
-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
+fig.update_layout(
+    xaxis_title="X Variable",
+    yaxis_title="Y Variable",
+    font=dict(size=12)
+)
 
-## 5. Format for Publication
+fig.show()
+```
 
-Prepare your notebook for publication:
+### Statistical Visualizations
+```{code-cell} python
+import altair as alt
+
+# Create interactive Altair chart
+chart = alt.Chart(data).mark_circle().encode(
+    x='x_value:Q',
+    y='y_value:Q',
+    color='category:N',
+    size='magnitude:Q',
+    tooltip=['x_value', 'y_value', 'category', 'condition']
+).interactive()
+
+chart.properties(
+    title='Interactive Statistical Visualization',
+    width=600,
+    height=400
+)
+```
 
-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.)
+### Time Series Analysis
+```{code-cell} python
+import plotly.graph_objects as go
+
+# Create time series plot
+fig = go.Figure()
+
+for condition in data['condition'].unique():
+    subset = data[data['condition'] == condition]
+    fig.add_trace(go.Scatter(
+        x=subset['time'],
+        y=subset['value'],
+        mode='lines+markers',
+        name=condition,
+        hovertemplate='Time: %{x}<br>Value: %{y}<br>Condition: ' + condition
+    ))
+
+fig.update_layout(
+    title='Time Series Analysis by Condition',
+    xaxis_title='Time',
+    yaxis_title='Value',
+    hovermode='x unified'
+)
+
+fig.show()
+```
 
-## 6. Collaborate and Review
+## 5. Add Citations and References
 
-Work with co-authors effectively:
+Include academic citations using MyST syntax:
 
-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
+### Literature Review Section
+```{myst}
+## Literature Review
 
-## Best Practices
+Recent studies have shown significant progress in this field @jones2023; @brown2022. 
+The work by @smith2023 provides a comprehensive framework for understanding these patterns.
+
+Our approach builds upon the methodology described by @wilson2021, extending it to handle 
+larger datasets and more complex experimental conditions.
+```
 
-### Code Organization
-- **Clear variable names** and comments
-- **Modular functions** for reusability
-- **Error handling** for robustness
-- **Documentation** for complex algorithms
+### Create Bibliography
+Add a bibliography section to your paper:
 
-### Writing Style
-- **Clear, concise language** in markdown cells
-- **Proper scientific tone** and terminology
-- **Logical flow** between sections
-- **Consistent formatting** throughout
+```{myst}
+## References
 
-### Data Management
-- **Reproducible code** with fixed random seeds
-- **Data versioning** and backup
-- **Clear data sources** and citations
-- **Open data** when possible
+```{bibliography}
+:style: apa
+```
+```
+
+### BibTeX File Example
+Create a `references.bib` file:
+```bibtex
+@article{jones2023,
+  title={Recent advances in computational methods for scientific analysis},
+  author={Jones, A. and Wilson, B. and Davis, C.},
+  journal={Nature},
+  year={2023},
+  volume={123},
+  pages={456--789},
+  doi={10.1038/nature12345}
+}
+
+@article{brown2022,
+  title={Novel approaches to data analysis in experimental sciences},
+  author={Brown, C. and Miller, D.},
+  journal={Science},
+  year={2022},
+  volume={456},
+  pages={123--456},
+  doi={10.1126/science.abc1234}
+}
+
+@article{smith2023,
+  title={A comprehensive framework for scientific computing},
+  author={Smith, J. and Johnson, K.},
+  journal={Computational Science},
+  year={2023},
+  volume={78},
+  pages={234--567},
+  doi={10.1016/j.compsci.2023.123456}
+}
+```
+
+## 6. Cross-Reference Content
+
+Link to figures, tables, and sections throughout your paper:
+
+### Reference Figures and Tables
+```{myst}
+## Results
+
+Our analysis produced several key visualizations. The main results are shown in {numref}`Figure %s <fig:main_results>`, 
+and detailed statistics are presented in {numref}`Table %s <tbl:statistics>`.
+
+## Discussion
+
+As shown in {numref}`Figure %s <fig:main_results>`, the data reveals clear patterns that support our hypothesis.
+The statistical analysis presented in {numref}`Table %s <tbl:statistics>` confirms the significance of these findings.
+```
+
+### Section References
+```{myst}
+## Methods
+
+Our computational approach follows the methodology described in {numref}`Section %s <sec:data_preprocessing>`.
+
+## Data Preprocessing
+:label: sec:data_preprocessing
+
+Detailed description of data preprocessing steps...
+```
+
+## 7. Ensure Reproducibility
+
+Make your research reproducible with proper documentation:
+
+### Set Random Seeds
+```{code-cell} python
+import numpy as np
+import random
+
+# Set seeds for reproducibility
+np.random.seed(42)
+random.seed(42)
+
+print("Random seeds set for reproducible results")
+```
+
+### Document Dependencies
+```{code-cell} python
+# Document package versions for reproducibility
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+import plotly.express as px
+import altair as alt
+
+print("Package versions for reproducibility:")
+print(f"pandas: {pd.__version__}")
+print(f"numpy: {np.__version__}")
+print(f"matplotlib: {plt.matplotlib.__version__}")
+print(f"seaborn: {sns.__version__}")
+print(f"plotly: {px.__version__}")
+```
+
+### Error Handling
+```{code-cell} python
+def load_data_safely(filepath):
+    """Load data with proper error handling."""
+    try:
+        data = pd.read_csv(filepath)
+        print(f"Successfully loaded {len(data)} rows from {filepath}")
+        return data
+    except FileNotFoundError:
+        print(f"Error: File {filepath} not found")
+        return None
+    except Exception as e:
+        print(f"Error loading data: {e}")
+        return None
+
+# Use the safe loading function
+data = load_data_safely('experiment_data.csv')
+```
+
+## 8. Publish Your Jupyter Paper
+
+Export and deploy your scientific paper:
+
+### Export to Curvenote
+```bash
+# Initialize a Curvenote project
+curvenote init my-scientific-paper
+
+# Add your notebook
+curvenote add paper.ipynb
+
+# Build and preview
+curvenote build
+curvenote serve
+```
+
+### Configure Project Settings
+Create `curvenote.yml`:
+```yaml
+project:
+  title: "My Scientific Paper"
+  description: "Computational analysis of experimental data"
+  
+  # Enable Jupyter features
+  jupyter:
+    execute: true
+    interactive: true
+    
+  # Computational environment
+  computational:
+    binderhub: true
+    jupyter: true
+    
+  # Bibliography
+  bibliography:
+    - references.bib
+```
+
+### Deploy Your Paper
+```bash
+# Deploy to curve.space
+curvenote deploy
+
+# Your paper will be available at:
+# https://your-paper.curve.space
+```
 
 ## 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)
+- [Add Citations and References →](./citations.md)
+- [Create Interactive Figures →](./figures-and-images.md)
+- [Organize Your Content →](./organize-content.md)
+- [Learn about Computational Articles →](../computational-articles.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.
+💡 **Tip:** Start with a clear structure using Markdown cells, then add code cells for your analysis. Use interactive visualizations to engage readers and make your research more accessible.
 
-⚡ **Important:
-Reproducible Research Best Practices**
+⚡ **Important: Jupyter 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
+- **Clear documentation**: Use Markdown cells to explain your methodology
+- **Reproducible code**: Set random seeds and document dependencies
+- **Interactive outputs**: Use libraries that remain interactive in Curvenote
+- **Version control**: Save versions of your notebook as you develop
+- **Collaboration**: Share your notebook with colleagues for review and feedback
diff --git a/authoring/latex.md b/authoring/latex.md
index 4511544..04088c2 100644
--- a/authoring/latex.md
+++ b/authoring/latex.md
@@ -3,6 +3,513 @@ title: Writing a Scientific Paper using LaTeX
 short_title: Write using LaTeX
 ---
 
-:::{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)
-:::
+# Writing a Scientific Paper using LaTeX
+
+## Quick Start
+Create publication-quality scientific papers using LaTeX with Curvenote, combining traditional typesetting with modern collaborative features
+
+LaTeX is the gold standard for scientific and academic writing, offering precise control over formatting, mathematical equations, and publication-ready output. Curvenote provides seamless LaTeX integration, allowing you to write in MyST Markdown and export to LaTeX, or work directly with LaTeX files while maintaining version control and collaboration features.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project to write your paper in
+- LaTeX distribution installed (TeX Live, MiKTeX, or MacTeX)
+- Understanding of LaTeX syntax and structure
+- Journal template or formatting requirements
+- Access to the Curvenote editor interface
+
+## 1. Set Up Your LaTeX Environment
+
+Install and configure LaTeX for scientific writing:
+
+### Install LaTeX Distribution
+```bash
+# For Ubuntu/Debian
+sudo apt-get install texlive-full
+
+# For macOS (using Homebrew)
+brew install --cask mactex
+
+# For Windows
+# Download and install MiKTeX from https://miktex.org/
+```
+
+### Install Required Packages
+```bash
+# Install additional LaTeX packages
+tlmgr install amsmath amssymb geometry hyperref natbib
+tlmgr install graphics graphicx subcaption booktabs
+tlmgr install algorithm algorithmic listings
+```
+
+### Verify Installation
+```bash
+# Check LaTeX installation
+latex --version
+pdflatex --version
+```
+
+## 2. Structure Your LaTeX Paper
+
+Organize your paper with standard LaTeX document structure:
+
+### Basic Document Structure
+```latex
+\documentclass[11pt,a4paper]{article}
+
+% Preamble
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{amsmath,amssymb}
+\usepackage{graphicx}
+\usepackage{hyperref}
+\usepackage{natbib}
+
+% Document metadata
+\title{Your Scientific Paper Title}
+\author{Your Name}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+Your abstract goes here. This should provide a brief summary of your research question, methods, and key findings.
+\end{abstract}
+
+\section{Introduction}
+Background information, research objectives, and significance of your work.
+
+\section{Methods}
+Detailed description of your approach, data sources, and analysis methods.
+
+\section{Results}
+Presentation of your findings with tables, figures, and statistical analysis.
+
+\section{Discussion}
+Interpretation of results, implications, and future research directions.
+
+\bibliographystyle{plainnat}
+\bibliography{references}
+
+\end{document}
+```
+
+### Advanced Document Structure
+```latex
+\documentclass[11pt,a4paper]{article}
+
+% Enhanced preamble
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{amsmath,amssymb,amsfonts}
+\usepackage{graphicx,subcaption}
+\usepackage{hyperref}
+\usepackage{natbib}
+\usepackage{geometry}
+\usepackage{booktabs}
+\usepackage{algorithm}
+\usepackage{algorithmic}
+\usepackage{listings}
+
+% Page setup
+\geometry{margin=1in}
+\hypersetup{colorlinks=true,linkcolor=blue,citecolor=blue}
+
+% Custom commands
+\newcommand{\todo}[1]{\textcolor{red}{TODO: #1}}
+\newcommand{\note}[1]{\textcolor{blue}{Note: #1}}
+
+\begin{document}
+
+\title{Advanced Scientific Paper Title}
+\author{Author Name}
+\date{\today}
+
+\maketitle
+
+\begin{abstract}
+Your comprehensive abstract here.
+\end{abstract}
+
+\tableofcontents
+\newpage
+
+\section{Introduction}
+\label{sec:introduction}
+
+\section{Methods}
+\label{sec:methods}
+
+\subsection{Data Collection}
+\label{subsec:data}
+
+\subsection{Analysis}
+\label{subsec:analysis}
+
+\section{Results}
+\label{sec:results}
+
+\section{Discussion}
+\label{sec:discussion}
+
+\section{Conclusion}
+\label{sec:conclusion}
+
+\bibliographystyle{plainnat}
+\bibliography{references}
+
+\end{document}
+```
+
+## 3. Write Mathematical Content
+
+Add complex mathematical equations and notation:
+
+### Inline Mathematics
+```latex
+The quadratic equation $ax^2 + bx + c = 0$ has solutions given by the quadratic formula.
+
+The correlation coefficient $r$ ranges from $-1$ to $+1$, where $r = 0$ indicates no correlation.
+
+The p-value threshold $\alpha = 0.05$ is commonly used in statistical testing.
+```
+
+### Display Equations
+```latex
+\begin{equation}
+    x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
+    \label{eq:quadratic}
+\end{equation}
+
+\begin{align}
+    y &= mx + b \\
+    &= 2.5x + 1.2
+    \label{eq:linear}
+\end{align}
+
+\begin{equation}
+    \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+    \label{eq:gaussian}
+\end{equation}
+```
+
+### Complex Mathematical Structures
+```latex
+\begin{equation}
+    \begin{split}
+        f(x) &= \sum_{i=1}^{n} w_i x_i + b \\
+        &= \mathbf{w}^T \mathbf{x} + b
+    \end{split}
+    \label{eq:linear_model}
+\end{equation}
+
+\begin{align}
+    \nabla \cdot \mathbf{E} &= \frac{\rho}{\epsilon_0} \\
+    \nabla \cdot \mathbf{B} &= 0 \\
+    \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\
+    \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \epsilon_0 \frac{\partial \mathbf{E}}{\partial t}
+    \label{eq:maxwell}
+\end{align}
+```
+
+## 4. Add Tables and Figures
+
+Create professional tables and include figures:
+
+### Professional Tables
+```latex
+\begin{table}[htbp]
+\centering
+\caption{Summary Statistics by Experimental Group}
+\label{tab:summary_stats}
+\begin{tabular}{lccccc}
+\toprule
+Group & N & Mean & SD & Min & Max \\
+\midrule
+Control & 25 & 15.2 & 2.1 & 12.1 & 18.9 \\
+Treatment A & 25 & 18.7 & 2.8 & 14.3 & 22.1 \\
+Treatment B & 25 & 17.3 & 2.5 & 13.8 & 20.5 \\
+\bottomrule
+\end{tabular}
+\end{table}
+```
+
+### Advanced Tables
+```latex
+\begin{table}[htbp]
+\centering
+\caption{Regression Results}
+\label{tab:regression}
+\begin{tabular}{lccccc}
+\toprule
+Variable & Coefficient & SE & t-value & p-value & 95\% CI \\
+\midrule
+Intercept & 2.45 & 0.31 & 7.90 & <0.001 & [1.84, 3.06] \\
+Age & 0.12 & 0.05 & 2.40 & 0.017 & [0.02, 0.22] \\
+Gender (Male) & -0.34 & 0.15 & -2.27 & 0.024 & [-0.64, -0.04] \\
+Education & 0.08 & 0.03 & 2.67 & 0.008 & [0.02, 0.14] \\
+\bottomrule
+\multicolumn{6}{l}{\footnotesize $R^2 = 0.23$, $F(3, 196) = 19.45$, $p < 0.001$}
+\end{tabular}
+\end{table}
+```
+
+### Including Figures
+```latex
+\begin{figure}[htbp]
+\centering
+\includegraphics[width=0.8\textwidth]{figures/results_plot.pdf}
+\caption{Experimental results showing significant differences between groups. Error bars represent standard error of the mean.}
+\label{fig:results}
+\end{figure}
+
+\begin{figure}[htbp]
+\centering
+\begin{subfigure}[b]{0.48\textwidth}
+    \includegraphics[width=\textwidth]{figures/plot_a.pdf}
+    \caption{Control group results}
+    \label{fig:control}
+\end{subfigure}
+\hfill
+\begin{subfigure}[b]{0.48\textwidth}
+    \includegraphics[width=\textwidth]{figures/plot_b.pdf}
+    \caption{Treatment group results}
+    \label{fig:treatment}
+\end{subfigure}
+\caption{Comparison of experimental outcomes between control and treatment groups.}
+\label{fig:comparison}
+\end{figure}
+```
+
+## 5. Add Citations and References
+
+Include academic citations using BibTeX:
+
+### Citation Commands
+```latex
+\section{Literature Review}
+
+Recent studies have shown significant progress in this field \citep{jones2023, brown2022}. 
+The work by \citet{smith2023} provides a comprehensive framework for understanding these patterns.
+
+Our approach builds upon the methodology described by \citet{wilson2021}, extending it to handle 
+larger datasets and more complex experimental conditions.
+
+Multiple studies have demonstrated the effectiveness of this approach \citep[see][]{jones2023, brown2022, smith2023}.
+```
+
+### BibTeX File
+Create a `references.bib` file:
+```bibtex
+@article{jones2023,
+  title={Recent advances in computational methods for scientific analysis},
+  author={Jones, A. and Wilson, B. and Davis, C.},
+  journal={Nature},
+  year={2023},
+  volume={123},
+  pages={456--789},
+  doi={10.1038/nature12345}
+}
+
+@article{brown2022,
+  title={Novel approaches to data analysis in experimental sciences},
+  author={Brown, C. and Miller, D.},
+  journal={Science},
+  year={2022},
+  volume={456},
+  pages={123--456},
+  doi={10.1126/science.abc1234}
+}
+
+@article{smith2023,
+  title={A comprehensive framework for scientific computing},
+  author={Smith, J. and Johnson, K.},
+  journal={Computational Science},
+  year={2023},
+  volume={78},
+  pages={234--567},
+  doi={10.1016/j.compsci.2023.123456}
+}
+
+@book{wilson2021,
+  title={Advanced Methods in Scientific Research},
+  author={Wilson, R.},
+  year={2021},
+  publisher={Academic Press},
+  address={New York}
+}
+```
+
+## 6. Cross-Reference Content
+
+Link to figures, tables, and sections throughout your paper:
+
+### Cross-References
+```latex
+\section{Results}
+
+Our analysis produced several key visualizations. The main results are shown in Figure~\ref{fig:results}, 
+and detailed statistics are presented in Table~\ref{tab:summary_stats}.
+
+\section{Discussion}
+
+As shown in Figure~\ref{fig:results}, the data reveals clear patterns that support our hypothesis.
+The statistical analysis presented in Table~\ref{tab:summary_stats} confirms the significance of these findings.
+
+Our methodology, described in Section~\ref{sec:methods}, follows established protocols in the field.
+```
+
+### Automatic Numbering
+```latex
+\section{Methods}
+\label{sec:methods}
+
+Our computational approach follows the methodology described in Section~\ref{subsec:data}.
+
+\subsection{Data Collection}
+\label{subsec:data}
+
+Detailed description of data collection procedures...
+
+\subsection{Analysis}
+\label{subsec:analysis}
+
+Analysis methods build upon the data collection described in Section~\ref{subsec:data}.
+```
+
+## 7. Use Journal Templates
+
+Apply specific journal formatting requirements:
+
+### Journal-Specific Templates
+```latex
+% For Nature journal
+\documentclass[11pt]{article}
+\usepackage{nature}
+
+% For Science journal
+\documentclass[11pt]{article}
+\usepackage{science}
+
+% For IEEE journals
+\documentclass[conference]{IEEEtran}
+
+% For ACM journals
+\documentclass[acmsmall]{acmart}
+```
+
+### Custom Template Setup
+```latex
+\documentclass[11pt,a4paper]{article}
+
+% Journal-specific packages
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{amsmath,amssymb}
+\usepackage{graphicx}
+\usepackage{hyperref}
+\usepackage{natbib}
+
+% Journal-specific formatting
+\usepackage[margin=1in]{geometry}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{6pt}
+
+% Custom commands for journal
+\newcommand{\journalname}{Journal of Scientific Research}
+\newcommand{\volumenumber}{42}
+\newcommand{\issuenumber}{3}
+\newcommand{\articlenumber}{12345}
+
+\begin{document}
+
+\title{Your Paper Title}
+\author{Your Name}
+\date{\today}
+
+\maketitle
+
+% Journal-specific abstract format
+\begin{abstract}
+Your abstract here.
+\end{abstract}
+
+\keywords{keyword1, keyword2, keyword3}
+
+% Rest of your paper...
+```
+
+## 8. Compile and Export
+
+Build your LaTeX document and export from Curvenote:
+
+### Local Compilation
+```bash
+# Basic compilation
+pdflatex your_paper.tex
+
+# With bibliography
+pdflatex your_paper.tex
+bibtex your_paper
+pdflatex your_paper.tex
+pdflatex your_paper.tex
+
+# With index
+pdflatex your_paper.tex
+makeindex your_paper
+pdflatex your_paper.tex
+```
+
+### Curvenote Export
+```bash
+# Export to LaTeX using Curvenote CLI
+curvenote export latex
+
+# Export with specific template
+curvenote export latex --template nature
+
+# Export with custom output name
+curvenote export latex --output my_paper.tex
+```
+
+### Export Configuration
+Create `curvenote.yml`:
+```yaml
+project:
+  title: "My LaTeX Scientific Paper"
+  description: "Research paper in LaTeX format"
+  
+  # LaTeX export settings
+  export:
+    latex:
+      template: article
+      bibliography: references.bib
+      figures: true
+      tables: true
+      
+  # Bibliography settings
+  bibliography:
+    - references.bib
+```
+
+## Next Steps
+
+- [Add Citations and References →](./citations.md)
+- [Create Interactive Figures →](./figures-and-images.md)
+- [Organize Your Content →](./organize-content.md)
+- [Export to LaTeX →](../editor/export-latex.md)
+
+---
+
+💡 **Tip:** Start with a basic LaTeX structure, then add complexity as needed. Use Curvenote's version control to track changes and collaborate with co-authors.
+
+⚡ **Important: LaTeX Best Practices**
+
+- **Consistent formatting**: Use consistent command naming and structure
+- **Modular organization**: Break large documents into separate files
+- **Version control**: Track changes to your LaTeX source files
+- **Template compliance**: Follow journal-specific formatting requirements
+- **Bibliography management**: Keep BibTeX files organized and up-to-date
diff --git a/authoring/link-data-code.md b/authoring/link-data-code.md
new file mode 100644
index 0000000..a0be732
--- /dev/null
+++ b/authoring/link-data-code.md
@@ -0,0 +1,270 @@
+---
+title: Link Data and Code
+short_title: Link Data & Code
+---
+
+# Link Data and Code
+
+## Quick Start
+Connect your Curvenote articles to external datasets, code repositories, and computational resources for reproducible research
+
+Curvenote provides multiple ways to link your content to external data sources, code repositories, and computational environments. This enables readers to access the underlying data, run your code, and reproduce your research findings.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content you want to link to data/code
+- Access to external data sources or code repositories
+- URLs or DOIs for the resources you want to link
+- Understanding of your data's size and accessibility requirements
+
+## 1. Link to External Datasets
+
+Connect your articles to datasets stored in external repositories:
+
+### Using DOIs for Datasets
+For datasets with Digital Object Identifiers (DOIs):
+
+**Example in your article:**
+
+```markdown
+## Data Availability
+
+The dataset used in this analysis is available at:
+[Dataset DOI: 10.5281/zenodo.1234567](https://doi.org/10.5281/zenodo.1234567)
+```
+
+**Code to access the data:**
+
+```{code-cell} python
+import pandas as pd
+
+# Download dataset from DOI
+data_url = "https://zenodo.org/record/1234567/files/dataset.csv"
+data = pd.read_csv(data_url)
+```
+
+### Large-Scale Data Management
+For datasets larger than 50GB, use dedicated repositories:
+
+**Recommended repositories:**
+- **Zenodo**: For datasets under 50GB with DOI support
+- **Source Cooperative**: For open science projects
+- **Field-specific repositories**: For specialized data types
+
+**Configuration in `curvenote.yml`:**
+```yaml
+project:
+  requirements:
+    - environment.yml
+  resources:
+    - some_resource_file.csv
+    - url: https://doi.org/123456.qwerty
+      file: data/local_path_my_notebooks_expect.hd5
+```
+
+## 2. Link to Code Repositories
+
+Connect your content to source code and computational notebooks:
+
+### GitHub Integration
+Link to GitHub repositories containing your code:
+
+**Example in your article:**
+
+```markdown
+## Code Availability
+
+The complete code for this analysis is available at:
+[GitHub Repository](https://github.com/username/project-name)
+```
+
+**Code to set up the environment:**
+
+```{code-cell} python
+# Clone the repository
+!git clone https://github.com/username/project-name.git
+%cd project-name
+
+# Install dependencies
+!pip install -r requirements.txt
+```
+
+### Jupyter Notebook Integration
+Link to specific notebooks or code cells:
+
+**Example in your article:**
+
+```markdown
+## Analysis Code
+
+The complete analysis is available in the Jupyter notebook:
+[Analysis Notebook](https://github.com/username/project-name/blob/main/analysis.ipynb)
+```
+
+**Code to use the functions:**
+
+```{code-cell} python
+# Import functions from the repository
+from analysis_functions import process_data, create_visualization
+
+# Use the imported functions
+results = process_data(dataset)
+create_visualization(results)
+```
+
+## 3. Configure Computational Resources
+
+Set up your project for reproducible computation:
+
+### Environment Configuration
+Define computational requirements in your project:
+
+**Create `environment.yml`:**
+```yaml
+name: my-research
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.9
+  - pandas
+  - numpy
+  - matplotlib
+  - jupyter
+  - pip
+  - pip:
+    - plotly
+    - seaborn
+```
+
+**Reference in `curvenote.yml`:**
+```yaml
+project:
+  requirements:
+    - environment.yml
+  computational:
+    - binderhub: true
+    - jupyter: true
+```
+
+### Data Resource Management
+Configure data resources for automatic download:
+
+```yaml
+project:
+  resources:
+    # Local data files
+    - data/experiment_results.csv
+    - data/calibration_data.h5
+    
+    # External datasets with DOIs
+    - url: https://doi.org/10.5281/zenodo.1234567
+      file: data/external_dataset.csv
+    
+    # Large datasets
+    - url: https://doi.org/123456.qwerty
+      file: data/large_dataset.hd5
+```
+
+## 4. Create Interactive Data Links
+
+Enable readers to interact with your data directly:
+
+### Deep Dive Links
+Create links that allow readers to explore data in detail:
+
+**Example in your article:**
+
+```markdown
+## Data Exploration
+
+Explore the dataset interactively:
+[Interactive Data Explorer](https://your-site.curve.space/data-explorer)
+
+## Key Findings
+
+The analysis reveals significant patterns in the data:
+- **Trend 1**: [View in Data Explorer](https://your-site.curve.space/data-explorer#trend1)
+- **Trend 2**: [View in Data Explorer](https://your-site.curve.space/data-explorer#trend2)
+```
+
+### Launch Jupyter Integration
+Enable readers to run your code:
+
+**Example in your article:**
+
+```markdown
+## Reproduce This Analysis
+
+Click the "Launch Jupyter" button above to run this analysis interactively.
+```
+
+**Code for data processing:**
+
+```{code-cell} python
+# This code will run in the Jupyter environment
+import pandas as pd
+import numpy as np
+
+# Load the dataset
+data = pd.read_csv('data/experiment_results.csv')
+
+# Process the data
+processed_data = data.groupby('condition').mean()
+processed_data
+```
+
+## 5. Manage Large Datasets
+
+Handle datasets that are too large for direct inclusion:
+
+### Pre-fetching Large Data
+Configure automatic data download during build:
+
+```yaml
+project:
+  resources:
+    # Large dataset will be downloaded during build
+    - url: https://doi.org/123456.qwerty
+      file: data/large_dataset.hd5
+      pre_fetch: true
+```
+
+### Data Repository Integration
+Link to external data repositories:
+
+**Example in your article:**
+
+```markdown
+## Large Dataset Access
+
+The full dataset (2.3TB) is available from:
+[Data Repository](https://repository.example.com/dataset)
+```
+
+**Code to access sample data:**
+
+```{code-cell} python
+# Load sample data
+sample_data = pd.read_csv('data/sample_dataset.csv')
+sample_data.head()
+```
+
+## Next Steps
+
+- [Add Interactive Figures →](./interactive-figures.md)
+- [Organize Your Content →](./organize-content.md)
+- [Create Computational Articles →](../computational-articles.md)
+
+---
+
+💡 **Tip:** Always provide both a DOI and a direct download link for your datasets to ensure long-term accessibility and immediate access.
+
+⚡ **Important: Data and Code Best Practices**
+
+- **Use DOIs**: Always obtain DOIs for datasets to ensure long-term accessibility
+- **Version control**: Keep your code in version-controlled repositories
+- **Documentation**: Provide clear instructions for reproducing your analysis
+- **Data size**: Use external repositories for datasets larger than 50GB
+- **Licensing**: Ensure your data and code have appropriate licenses for reuse
diff --git a/authoring/markdown-myst-jupyter.md b/authoring/markdown-myst-jupyter.md
new file mode 100644
index 0000000..8faccfa
--- /dev/null
+++ b/authoring/markdown-myst-jupyter.md
@@ -0,0 +1,179 @@
+---
+title: Writing with Markdown, MyST, or Jupyter
+short_title: Writing Formats
+---
+
+# Writing with Markdown, MyST, or Jupyter
+
+## Quick Start
+Choose the right writing format for your content: standard Markdown for simple documents, MyST Markdown for scientific papers, or Jupyter notebooks for computational work
+
+Curvenote supports multiple writing formats to match your content needs. Use standard Markdown for basic documents, MyST Markdown for publication-quality scientific papers with citations and cross-references, or Jupyter notebooks for interactive computational content with code and outputs.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project to write in
+- Understanding of your content type and requirements
+- Access to the Curvenote editor interface
+- Content you want to create or convert
+
+## 1. Choose Your Writing Format
+
+### Standard Markdown
+**Best for**: Basic documents, simple formatting, quick notes, documentation
+
+**Features**:
+- Simple syntax, easy to learn
+- Basic formatting (headings, lists, links, code blocks)
+- Fast writing and editing
+- Universal compatibility
+
+**Example use cases**:
+- README files
+- Simple documentation
+- Quick notes and drafts
+- Basic articles
+
+### MyST Markdown
+**Best for**: Scientific papers, publications, academic content, citations
+
+**Features**:
+- All standard Markdown features
+- Academic citations and references
+- Cross-references and automatic numbering
+- Math equations and complex formatting
+- Publication-quality output
+
+**Example use cases**:
+- Research papers
+- Academic articles
+- Technical documentation
+- Books and reports
+
+### Jupyter Notebooks
+**Best for**: Computational work, data analysis, interactive content, reproducible research
+
+**Features**:
+- Code execution and interactive outputs
+- Rich visualizations and plots
+- Reproducible computational workflows
+- Integration with scientific libraries
+
+**Example use cases**:
+- Data analysis reports
+- Computational research papers
+- Interactive tutorials
+- Scientific workflows
+
+### Mixed Approach
+Combine formats within a single project for maximum flexibility.
+
+## 2. Quick Format Comparison
+
+| Feature | Standard Markdown | MyST Markdown | Jupyter Notebooks |
+|---------|------------------|---------------|-------------------|
+| **Learning Curve** | Easy | Medium | Medium-Hard |
+| **Citations** | Manual | Automatic | Automatic |
+| **Code Execution** | No | No | Yes |
+| **Interactive Outputs** | No | No | Yes |
+| **Cross-references** | Manual | Automatic | Automatic |
+| **Math Equations** | Basic | Advanced | Advanced |
+| **Publication Ready** | Basic | Yes | Yes |
+
+## 3. Decision Tree
+
+**Start here** → What type of content are you creating?
+
+- **Simple document or note?** → [Standard Markdown](#standard-markdown)
+- **Academic paper with citations?** → [MyST Markdown](#myst-markdown)
+- **Computational work with code?** → [Jupyter Notebooks](#jupyter-notebooks)
+
+## 4. Standard Markdown Basics
+
+**Headings**: `# H1`, `## H2`, `### H3` for document structure
+
+**Text formatting**: `**bold**`, `*italic*`, `` `code` `` for emphasis
+
+**Lists**: `- bullet` or `1. numbered` for organized content
+
+**Links**: `[text](url)` for external references
+
+**Code blocks**: ` ```language` for syntax-highlighted code
+
+## 5. MyST Markdown Features
+
+**Citations**: `@cite-key` or `@10.5281/zenodo.123456` for references
+
+**Cross-references**: `@fig:label` or `@tbl:label` for figure/table links
+
+**Math equations**: `$inline$` or `$$block$$` for mathematical content
+
+**Directives**: `:::{note}` for callouts, `:::{figure}` for captioned images
+
+**Footnotes**: `[^1]` and `[^1]: definition` for additional notes
+
+:::{seealso} Detailed MyST Guide
+For comprehensive MyST Markdown documentation, see [MyST Markdown Guide](./myst-markdown.md).
+:::
+
+## 6. Jupyter Notebooks Overview
+
+**Code cells**: Write and execute Python, R, or other languages
+
+**Markdown cells**: Add explanations and documentation
+
+**Output cells**: Display results, plots, and interactive visualizations
+
+**Cell types**: Code, Markdown, and Output cells work together
+
+**Interactive outputs**: Plotly, Altair, Bokeh, Matplotlib remain interactive
+
+:::{seealso} Comprehensive Jupyter Guide
+For detailed Jupyter notebook workflows and scientific paper creation, see [Writing with Jupyter Notebooks](./jupyter-notebooks.md).
+:::
+
+## 7. Getting Started with Each Format
+
+### Standard Markdown
+1. Create a new `.md` file in your project
+2. Start writing with basic markdown syntax
+3. Use the Curvenote editor for live preview
+
+### MyST Markdown
+1. Create a new `.md` file in your project
+2. Add frontmatter with title and metadata
+3. Use MyST directives for advanced features
+4. Add citations and cross-references
+
+### Jupyter Notebooks
+1. Create a new `.ipynb` file or import existing notebook
+2. Structure with Markdown cells for narrative
+3. Add code cells for computational work
+4. Include interactive visualizations
+
+## Next Steps
+
+**For Standard Markdown**: Start writing! No additional setup needed.
+
+**For MyST Markdown**: 
+- [Add Citations and References →](./citations.md)
+- [Add Figures and Images →](./figures-and-images.md)
+- [Learn MyST Directives →](./myst-markdown.md)
+
+**For Jupyter Notebooks**:
+- [Writing Scientific Papers with Jupyter →](./jupyter-notebooks.md)
+- [Interactive Outputs →](../editor/interactive-outputs-in-jupyter.md)
+- [Reproducible Figures →](../editor/reproducible-figures.md)
+
+---
+
+💡 **Tip:** Start with standard Markdown for simple content, then upgrade to MyST Markdown when you need citations, cross-references, or publication-quality formatting. Use Jupyter notebooks when your content includes code execution or interactive outputs.
+
+⚡ **Important: Writing Format Best Practices**
+
+- **Choose wisely**: Match format to content type and complexity
+- **Consistent formatting**: Use consistent heading levels and structure
+- **Citation management**: Keep BibTeX files organized and up-to-date
+- **Cross-references**: Use labels consistently for reliable linking
+- **Code documentation**: Always document code cells in Jupyter notebooks
diff --git a/authoring/myst-markdown.md b/authoring/myst-markdown.md
deleted file mode 100644
index a7c537c..0000000
--- a/authoring/myst-markdown.md
+++ /dev/null
@@ -1,166 +0,0 @@
----
-title: Writing a Scientific Paper using MyST
-short_title: Using MyST Markdown
-description: Curvenote uses a flavour of Markdown called MyST Markdown, which is designed to create publication-quality, computational documents written entirely in Markdown.
----
-
-:::{tip} Objective
-The goal of this overview is to introduce MyST Markdown and commonly used features necessary to write a scientific paper 📄.
-MyST Markdown is bundled directly in Curvenote, and can be accessed through the CLI, which you can [install locally](../cli/index.md).
-:::
-
-Curvenote uses a flavour of Markdown called [MyST Markdown](https://mystmd.org) (Markedly Structured Text), which is designed to create publication-quality, computational documents written entirely in Markdown.
-
-:::{important} Getting Started
-To get started [install Curvenote CLI](../cli/index.md).
-:::
-
-````{note} See the video tutorial 📺
-:class: dropdown
-```{iframe} https://www.youtube.com/embed/NxSNVt9XsCI
-:width: 100%
-```
-````
-
-## MyST Markdown Overview
-
-MyST is a superset of [CommonMark](https://commonmark.org/) (a standard form of Markdown) with special syntax for citations, cross-references, and block and inline extension points called "directives" and "roles".
-MyST is influenced by [reStructuredText (RST)](https://en.wikipedia.org/wiki/reStructuredText) and [Sphinx](https://www.sphinx-doc.org) – pulling on the nomenclature and introducing additional standards where appropriate.
-
-## Typography
-
-The official documentation for MyST Markdown is found on [mystmd.org](https://mystmd.org/guide), below we give some brief documentation for writing content.
-
-### Basic Markdown
-
-Documents are Markdown, `.md`, and have additional features when compiled with a tool like the curvenote or `mystmd` CLIs. A full list of the syntax can be found in the [typography documentation](https://mystmd.org/guide/typography), including `###` for headings, `_` for emphasis, `**` for strong, backticks for `` `code` ``, and `-` for bullet points.
-
-```{myst}
-## An important heading
-
-1. Use a `-` for lists and `1.` for enumerated lists
-
-- We can see _emphasis_, and **strong** `code`
-
-> This is a block quotation with a [link](https://curvenote.com)
-```
-
-### Extended Typography
-
-In addition to the basic markdown, MyST includes extended typography for things like [definition lists](https://mystmd.org/guide/typography#definition-lists), [footnotes](https://mystmd.org/guide/typography#footnotes), [superscript](https://mystmd.org/guide/typography#subscript-superscript), [quotation authors](https://mystmd.org/guide/typography#quotations), and [task lists](https://mystmd.org/guide/typography#task-lists).
-
-```{myst}
-Term 1
-: This is an important term[^myref]
-
-> A watery quote about H{sub}`2`O,
->
-> -- An author
-
-- [x] A completed task
-
-[^myref]: This is an auto-numbered footnote definition
-```
-
-### Citations
-
-Citations can be added inline using `@cite-key` syntax and having a BibTeX file in your project.
-You can also directly link to DOIs using `@10.5281/zenodo.6476040`, which will create a hover reference
-[@10.5281/zenodo.6476040] and a references section at the bottom of the page.
-For multiple references in a parenthetical use `[@cite-key1; @cite-key2]`.
-See the full MyST documentation on [citations and bibliographies](https://mystmd.org/guide/citations).
-
-## Block Content
-
-Block-level content, or directives, provide multi-line containers surrounded by either backticks or colons that include a type, arguments, options, and content. Examples include callout panels, figures, equations and tables. You can use directives using the following markup:
-
-```{myst}
-:::{note} Note Title
-:class: simple
-Here is a note!
-:::
-```
-
-The directive above is of type `note`, and can take an arguments of the note's title, as well as a number of options in `:key1: value` syntax. A common option to use is `label`, which allows for you to cross-reference content.
-
-:::{seealso} MyST Documentation on Directives
-Directives can be used for [figures](https://mystmd.org/guide/figures), [callouts](https://mystmd.org/guide/admonitions), [tables](https://mystmd.org/guide/tables), [proofs](https://mystmd.org/guide/proofs-and-theorems), [exercises](https://mystmd.org/guide/exercises), [mermaid diagrams](https://mystmd.org/guide/diagrams), and other visual elements. See the full [MyST Markdown](https://mystmd.org/guide) docs for all directives.
-:::
-
-### Figures
-
-In addition to the markdown `![](image.png)` syntax to create images, you can create figures in MyST with captions.
-These are the `{figure}` directive, and can be labeled and referenced using the same syntax as citations. The figure numbering is automatic. See [figure documentation](https://mystmd.org/guide/figures) for more.
-
-```{myst}
-:::{figure} https://source.unsplash.com/random/500x150?sunset
-:label: fig:sunset
-A beautiful sunset, with an informative caption.
-:::
-
-In @fig:sunset, you can see...
-```
-
-### Inline Math and Equations
-
-Equations can be created using a `{math}` directive and inline "dollar-math", both of these can also have a label and cross-referenced in text. See full documentation on [math and equations](https://mystmd.org/guide/math).
-
-````{myst}
-```{math}
-:label: my-equation
-w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
-```
-
-The term $s(w_t)$ in [](#my-equation) means
-````
-
-### Tables
-
-Tables can be created using [GFM tables](https://github.github.com/gfm/#tables-extension-) and a caption/label added using the `{table}` directive. See the [documentation on tables](https://mystmd.org/guide/tables).
-
-``````{tab-set}
-````{tab-item} GFM Table
-```{myst}
-:::{table} Table caption
-:label: table
-| foo | bar |
-| --- | --- |
-| baz | bim |
-:::
-```
-````
-`````{tab-item} List Table
-````{myst}
-```{list-table} This table title
-:header-rows: 1
-:name: example-table
-
-* - Training
-  - Validation
-* - 0
-  - 5
-* - 13720
-  - 2744
-```
-````
-`````
-``````
-
-## Cross Referencing
-
-Cross-references can be added in the exact same way as citations, using an `@fig:label` syntax, by default this adds the kind of the element that you are referencing and the auto-generated number (e.g. `Figure 12`).
-To get more specific about the way that you reference, you can use a markdown link: `[See %s](#fig:label)`, the `%s` will be replaced by the number (i.e. `See 12`). See [full documentation](https://mystmd.org/guide/cross-references) for information on additional targets, numbering and other rules.
-
-## Abstracts and Parts
-
-To define parts of your document, like an abstract, use the page frontmatter. The full [documentation on page parts](https://mystmd.org/guide/document-parts) shows how to create these inline or in a notebook cell.
-
-```{code-block} yaml
-:filename: article.md
----
-title: My Paper
-abstract: |
-  This is a multi-line
-  abstract.
----
-```
diff --git a/authoring/organize-content.md b/authoring/organize-content.md
new file mode 100644
index 0000000..ef6ffa6
--- /dev/null
+++ b/authoring/organize-content.md
@@ -0,0 +1,278 @@
+---
+title: Organize Content into Sections
+short_title: Organize Content
+---
+
+# Organize Content into Sections
+
+## Quick Start
+Structure your Curvenote project with folders, navigation groups, and table of contents to create a well-organized content hierarchy
+
+Curvenote provides multiple ways to organize your content, from simple folder structures to complex navigation hierarchies. Proper organization helps readers navigate your content and makes it easier to manage large projects with multiple articles, notebooks, and resources.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content you want to organize
+- A clear understanding of your content structure and hierarchy
+- Access to your project's configuration files
+- Content that can be logically grouped into sections
+
+## 1. Organize with Folder Structure
+
+Create a logical folder hierarchy for your content:
+
+### Basic Folder Organization
+Organize your content using folders in your project structure:
+
+```
+content/
+├── index.md                    # Main landing page
+├── introduction.md             # Introduction section
+├── methods/
+│   ├── data-collection.md      # Data collection methods
+│   ├── analysis.md             # Analysis methods
+│   └── validation.md           # Validation methods
+├── results/
+│   ├── experiment-1.md         # First experiment results
+│   ├── experiment-2.md         # Second experiment results
+│   └── comparison.md           # Results comparison
+├── discussion/
+│   ├── implications.md         # Research implications
+│   └── future-work.md          # Future research directions
+└── assets/
+    ├── figures/                # Image files
+    ├── data/                   # Dataset files
+    └── code/                   # Code files
+```
+
+### Folder Best Practices
+- **Use descriptive names**: Clear, meaningful folder names
+- **Keep it shallow**: Avoid deeply nested folders (max 3-4 levels)
+- **Group related content**: Put similar content together
+- **Separate assets**: Keep images, data, and code in dedicated folders
+
+## 2. Configure Table of Contents
+
+Set up navigation structure using `_toc.yml` files:
+
+### Basic Table of Contents
+Create a `_toc.yml` file in your content directory:
+
+```yaml
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: index
+chapters:
+  - file: introduction
+  - file: methods/data-collection
+  - file: methods/analysis
+  - file: methods/validation
+  - file: results/experiment-1
+  - file: results/experiment-2
+  - file: results/comparison
+  - file: discussion/implications
+  - file: discussion/future-work
+```
+
+### Advanced Table of Contents
+Create nested sections with subsections:
+
+```yaml
+# Table of contents
+format: jb-book
+root: index
+chapters:
+  - file: introduction
+  - title: Methods
+    sections:
+      - file: methods/data-collection
+      - file: methods/analysis
+      - file: methods/validation
+  - title: Results
+    sections:
+      - file: results/experiment-1
+      - file: results/experiment-2
+      - file: results/comparison
+  - title: Discussion
+    sections:
+      - file: discussion/implications
+      - file: discussion/future-work
+```
+
+## 3. Use Navigation Groups
+
+Organize content using Curvenote's navigation panel:
+
+### Create Navigation Groups
+1. **Access your project** in the Curvenote editor
+2. **Click the + button** at the bottom of the navigation panel
+3. **Select "Create Group"** to add a new navigation group
+4. **Name your group** with a descriptive title
+5. **Drag content** into the group to organize it
+
+### Group Organization
+- **Research Sections**: Group by research phases (methods, results, discussion)
+- **Content Types**: Separate articles, notebooks, and resources
+- **Topics**: Group by subject matter or themes
+- **Timeline**: Organize by publication date or research timeline
+
+### Navigation Best Practices
+- **Keep groups small**: 5-7 items per group maximum
+- **Use clear names**: Group titles should be descriptive
+- **Logical order**: Arrange content in a logical sequence
+- **Consistent structure**: Use similar organization across projects
+
+## 4. Structure Individual Documents
+
+Organize content within individual articles and notebooks:
+
+### Document Structure
+Use consistent heading hierarchy in your documents:
+
+```markdown
+# Main Title
+
+## Introduction
+Brief overview of the section
+
+### Background
+Context and previous work
+
+### Objectives
+What this section aims to achieve
+
+## Methods
+Description of the approach
+
+### Data Collection
+How data was gathered
+
+### Analysis
+How data was processed
+
+## Results
+Findings and outcomes
+
+### Key Findings
+Main results summary
+
+### Statistical Analysis
+Detailed statistical results
+
+## Discussion
+Interpretation and implications
+
+### Implications
+What the results mean
+
+### Limitations
+Study limitations and constraints
+
+## Conclusion
+Summary and next steps
+```
+
+### Heading Best Practices
+- **Use consistent hierarchy**: H1 → H2 → H3 → H4
+- **Descriptive titles**: Clear, specific section names
+- **Logical flow**: Information flows naturally between sections
+- **Balanced sections**: Similar depth across major sections
+
+## 5. Manage Multiple Projects
+
+Organize content across multiple projects in a single site:
+
+### Project Structure
+When working with multiple projects, organize them clearly:
+
+```yaml
+site:
+  nav:
+    - title: Home
+      url: /
+    - title: Research
+      children:
+        - title: Current Projects
+          url: /research/current
+        - title: Publications
+          url: /research/publications
+        - title: Data
+          url: /research/data
+    - title: Teaching
+      children:
+        - title: Courses
+          url: /teaching/courses
+        - title: Materials
+          url: /teaching/materials
+    - title: About
+      url: /about
+```
+
+### Project Organization
+- **Separate concerns**: Keep different types of content separate
+- **Clear navigation**: Make it easy to find specific content
+- **Consistent structure**: Use similar organization across projects
+- **Logical grouping**: Group related projects together
+
+## 6. Optimize for Different Content Types
+
+Organize based on your content type:
+
+### Research Articles
+```
+content/
+├── abstract.md
+├── introduction.md
+├── methods/
+├── results/
+├── discussion.md
+├── conclusion.md
+└── references.md
+```
+
+### Course Materials
+```
+content/
+├── syllabus.md
+├── lectures/
+│   ├── week-1/
+│   ├── week-2/
+│   └── week-3/
+├── assignments/
+├── resources/
+└── schedule.md
+```
+
+### Lab Website
+```
+content/
+├── index.md
+├── research/
+│   ├── projects/
+│   ├── publications/
+│   └── data/
+├── team/
+├── news/
+└── contact.md
+```
+
+## Next Steps
+
+- [Reuse Content Blocks →](./reuse-blocks.md)
+- [Manage Version History →](./version-history.md)
+- [Set Up Site Navigation →](../site-design/navigation.md)
+
+---
+
+💡 **Tip:** Start with a simple folder structure and refine it as your project grows. You can always reorganize content later as your needs evolve.
+
+⚡ **Important: Organization Best Practices**
+
+- **Plan ahead**: Think about your content structure before creating files
+- **Be consistent**: Use similar organization patterns across your projects
+- **Keep it simple**: Don't over-organize - simple structures are easier to maintain
+- **Document structure**: Include README files to explain your organization
+- **Regular review**: Periodically review and update your organization as content grows
diff --git a/authoring/reuse-blocks.md b/authoring/reuse-blocks.md
new file mode 100644
index 0000000..ae2e9b6
--- /dev/null
+++ b/authoring/reuse-blocks.md
@@ -0,0 +1,85 @@
+---
+title: Reuse Text, Figures, and Blocks
+short_title: Reuse Blocks
+---
+
+# Reuse Text, Figures, and Blocks
+
+## Quick Start
+Reuse content blocks, figures, and text across multiple Curvenote projects using the block system and oxa links
+
+Curvenote's block system allows you to create reusable content components that can be shared across articles, notebooks, and projects. All copies of a block are linked, meaning changes propagate to all instances, making it easy to maintain consistency and update content across multiple documents.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content you want to reuse
+- Access to the Curvenote editor interface
+- Content blocks that you want to share or reuse
+- Understanding of the block system and oxa links
+
+## 1. Understand the Block System
+
+Blocks are modular content units (text, figures, images, code outputs) that can be reused across projects. All copies are linked, so changes propagate to all instances automatically.
+
+## 2. Copy Block Links
+
+**Keyboard method**: Select block → `CTRL-C` (Windows/Linux) or `⌘-C` (Mac)
+
+**Menu method**: Select block → ⋮ Options → Copy Link
+
+**For specific versions**: Select block → Block Details Panel → version ⋮ Options → Copy Link
+
+## 3. Import Blocks into Documents
+
+**Keyboard method**: Enter Draft Mode → Select block → `CTRL-V` (Windows/Linux) or `⌘-V` (Mac)
+
+**Menu method**: Enter Draft Mode → Select block → ⋮ More Options → Import Block → Paste link → INSERT BLOCK
+
+## 4. Reuse Jupyter Outputs as Figures
+
+Copy oxa link from Jupyter output cell → Import into article → Format as figure if needed
+
+**Interactive outputs**: Plotly, Altair, Bokeh, Matplotlib, Pandas remain interactive when imported
+
+**Update outputs**: Edit code in Jupyter → Run cell → Save notebook → Changes propagate to all instances
+
+## 5. Reuse Code as Templates
+
+Copy oxa link → Import into new notebook/article → Make modifications as needed
+
+**For independent templates**: Import block → ⋮ Options → Unlink Block (versioning restarts, no propagation)
+
+**Best practices**: Document code, use descriptive names, organize by function
+
+## 6. Manage Block Versions
+
+Select block → Block Details Panel → Browse versions → Preview by clicking → USE VERSION or CLEAR PREVIEW
+
+**Version management**: All instances updated automatically, track changes, rollback capability, team collaboration
+
+## 7. Organize Reusable Content
+
+**Block Settings**: Select block → ⋮ Options → Block Settings → Add title, description, tags, thumbnail
+
+**Organization**: Create templates, use tags, document purpose, regular maintenance
+
+**Sharing**: Public blocks, team libraries, documentation, version control
+
+## Next Steps
+
+- [Manage Version History →](./version-history.md)
+- [Add Interactive Figures →](./interactive-figures.md)
+- [Organize Your Content →](./organize-content.md)
+
+---
+
+💡 **Tip:** Use descriptive titles and tags for your blocks to make them easier to find and reuse later. A well-organized block library saves time and ensures consistency across projects.
+
+⚡ **Important: Block Reuse Best Practices**
+
+- **Link when possible**: Keep blocks linked for automatic updates and consistency
+- **Unlink for templates**: Use unlinked copies when you want independent versions
+- **Version management**: Regularly review and update your reusable blocks
+- **Documentation**: Always document the purpose and usage of shared blocks
+- **Organization**: Use tags and titles to keep your block library organized
diff --git a/authoring/submitting-your-work.md b/authoring/submitting-your-work.md
deleted file mode 100644
index 534a03d..0000000
--- a/authoring/submitting-your-work.md
+++ /dev/null
@@ -1,183 +0,0 @@
----
-title: Submitting your work
----
-
-```{tip} Objective
-By the end of this guide you will be able to use the Curvenote CLI to submit your work to a site, check it's status and submit updates to it.
-
-The recommended starting point for this guide is a local MyST Project that you have already prepared using the [Preparing for Submission](preparing-for-submission.md) guide.
-
-If you have piece of work you are trying to submit for real, following this guide will take you through that process.
-
-If not then you can follow this guide with any MyST Project that builds to a website without issue and submit this to the `cn-testing` site. If you don't have a project you can use the [MyST quickstart project](https://github.com/executablebooks/mystmd-quickstart).
-```
-
-## Pre-requisites
-
-If you have not already done so:
-
-- [Install the Curvenote CLI](installing.md) and setup your [API Token](authentication.md)
-- Prepare a local folder containing your MyST submission OR clone the [quickstart project](https://github.com/executablebooks/mystmd-quickstart)
-- Open a terminal / command prompt and `cd` into that folder
-
-## Check your build
-
-Check that your work builds as expected by running `curvenote start` and opening the resulting link in your web browser.
-
-```{figure} images/curvenote-start.png
-:label: fig:curvenote-start
-:class: framed
-The result of running `curvenote start` showing the link to the web based preview of the work and various output logs and in this case warnings. Errors and warnings such as those shown for broken cross references  should be addressed before making a submission.
-```
-
-You should check that no errors appear on in the terminal after running `curvenote start`. Errors and warnings can point to problems with your work that should be addressed before submission.
-
-## The Site
-
-On Curvenote's platform you submit a work to a {term}`Site` ([learn about sites](../sites/index.md)).
-
-In this guide, we'll assume the site is a scientific journal that uses collections to organize it's publications by year and that at least one currently open for submission.
-
-To proceed with a submission, ensure your know the site and `collection` names and any other relevant information provided in the submission instructions by the site.
-
-If you are just practicing with a dummy submission, you can submit to `cn-testing`.
-
-```{warning} Sites with restricted submission
-:class: dropdown
-Sites such as research group or private sites restrict submissions to a specific set of Curvenote users via a publishing team.
-
-If this is the first time you are submitting to one of these sites you'll may need to contact your site administrator and ensure that your Curvenote user account has been added to the publishing team.
-```
-
-(doc:draft)=
-
-## Submit a draft
-
-So far using `curvenote start` and `curvenote check` has allowed you to screen for issues locally.
-
-You can also submit a {term}`draft` to the site which will allow you to check your submission using the site's build system, preview it on the site's website and if you are submitting a Computational Article or Notebook based Report, test the computational environment configuration is working correctly the site's servers.
-
-Drafts are completely standalone. They are not visible to or received by the site's editorial team and are removed after 30 days. You can make as many draft submissions as you like and they are only accessible using the link that it returned by the CLI.
-
-To submit a draft simple include the `--draft` argument when submitting:
-
-```bash
-% curvenote submit scipy --draft
-```
-
-Once the submit command is successfully completed, you will something like the following output:
-
-```{figure} images/curvenote-submit-draft.png
-:label: fig:curvenote-submit-draft
-:class: framed
-Final parts of the output from the `curvenote submit <site> --draft` command showing upload information and a link to the _"build"_ on Curvenote. Use this link to review the build outcome and access a preview of your draft submission on the site's website.
-```
-
-This like: https://sites.curvenote.com/build/018ee71b-9d20-760c-9090-d9e43d674112 to the _"build"_ information for your submission.
-
-The build page lists some of the metadata from your submission, includes a {term}`preview` link and lists all of the passing and failing checks on your submission. Additional detail and documentation is included for each check, which you can use to resolve remaining issues or satisfy optional requirements from the site.
-
-```{figure} images/curvenote-build-page.png
-:label: fig:curvenote-build-page
-:class: framed
-The build page for the `--draft` submission, although all submissions will generate a associated build page where you can access the preview and check summary.
-```
-
-Clicking on the _Preview_ button will open your submission in preview mode, where you will be able to see it within the theme/style of the site's website.
-
-```{figure} images/curvenote-draft-preview.png
-:label: fig:curvenote-draft-preview
-:class: framed
-A preview of the draft submission.
-```
-
-You can use this to check that all parts of your submission are present and correct, including additional pages of supporting information. If you have submitted a Computational Article or Notebook based Report then you will also be able to test launching a Jupyter instance and any interactive figures or inline notebook computation that the site enables.
-
-## Submit your work (for real)
-
-Once you have are happy with your submission, all your required checks pass and you have reviewed a draft submission - then it's time to submit for real. Once your submission is received by the site their editorial team will be notified and process it according to their editorial workflow.
-
-To make your submission for real simply type:
-
-```bash
-% curvenote submit <site>
-```
-
-And follow the prompts. The process will be the same as you saw when submitting your draft, and you'll be able to check the result of the build and preview your submission.
-
-### Collections and Kinds
-
-Sites may use _Collections_ to organize their content and invite submissions from authors at particular times. Sites also use _Submission Kinds_ to identify a particular type of submission for example Conference Abstract, Research Paper, Research Letter, etc...
-
-If a site you are submitting to has multiple Submission Kinds available or multiple Collections open, you will be prompted to select a Collection and/or Submission Kind.
-
-```{figure} images/curvenote-submit-collections.png
-:label: fig:curvenote-submit-collections
-:class: framed
-An toy example of a site with multiple collections open for submission.
-```
-
-### Tracking your submission
-
-Every MyST project has a unique `id`, and you can find this in the `curvenote.yml` or `myst.yml` file in your local folder. If you want to take a look, check for:
-
-```{code-block} yaml
-:filename: myst.yml or curvenote.yml
-:linenos:
-:emphasize-lines: 2
-project:
-    id: 838af10b-c919-48f8-98da-aadef3dab121
-    ...
-```
-
-If you haven't yet committed your `curvenote/myst.yml` file to version control, then this is a good time to do so. Keeping this file and `id` is essential for easily updating your submission in future.
-
-````{tip} Moving Faster
-:class: dropdown
-Once you are experienced with submitting using the CLI you may want to speed up the process. In which case you can make use of the additional command line arguments to minimize prompting.
-
-To get help on the available options run:
-
-```bash
-% curvenote submit --help
-Usage: curvenote submit [options] [site]
-
-Submit your work to a Site
-
-Arguments:
-  site                   Site to submit the work to
-
-Options:
-  --kind <string>         Submit to the site using this submission kind
-  --collection <string>   Submit to this collection at the site
-  --draft                 Make an draft submission
-  --new                   Start a new submission even if one already exists for the current work/site
-  -y, --yes               Use the defaults and answer "Y" to confirmations (default: false)
-  --resume                If a file upload fails, try to resume before raising an error. (default: false)
-  --max-size-webp <size>  Max image size to convert to webp format in MB (default: 1000)
-  -h, --help              display help for command
-```
-
-Note the `--kind` and `--collection` options, as well as the `-y` option for skipping confirmatory prompts.
-
-````
-
-## Check submission status
-
-Once your work has been submitted, you can monitor its status directly through the Curvenote CLI. To check the status of your submission, you can use the following command:
-
-```bash
-% curvenote submissions list
-```
-
-This command will list all of your submissions and their current statuses, such as "Pending", "In Review", "Rejected" or "Published."
-
-## Submit an update
-
-After your submission has been reviewed, you may need to make updates in response to feedback. To submit an updated version of your work, make the necessary changes to your local MyST project files and then simply re-run:
-
-```bash
-% curvenote submit <site>
-```
-
-You can again make draft submissions as needed (using the `--draft` keyword) before updating your submission.
diff --git a/authoring/typst.md b/authoring/typst.md
new file mode 100644
index 0000000..1e915b5
--- /dev/null
+++ b/authoring/typst.md
@@ -0,0 +1,563 @@
+---
+title: Writing a Scientific Paper using Typst
+short_title: Write using Typst
+---
+
+# Writing a Scientific Paper using Typst
+
+## Quick Start
+Create publication-quality scientific papers using Typst with Curvenote, combining modern typesetting with powerful mathematical notation and collaborative features
+
+Typst is a modern, fast typesetting system designed for scientific and academic writing. It offers LaTeX-like capabilities with improved performance, cleaner syntax, and better error messages. Curvenote provides seamless Typst integration, allowing you to write in MyST Markdown and export to Typst, or work directly with Typst files while maintaining version control and collaboration features.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project to write your paper in
+- Typst compiler installed (typst-cli)
+- Understanding of Typst syntax and structure
+- Journal template or formatting requirements
+- Access to the Curvenote editor interface
+
+## 1. Set Up Your Typst Environment
+
+Install and configure Typst for scientific writing:
+
+### Install Typst Compiler
+```bash
+# Using Cargo (Rust package manager)
+cargo install typst-cli
+
+# For macOS (using Homebrew)
+brew install typst
+
+# For Windows (using Chocolatey)
+choco install typst
+
+# For Ubuntu/Debian
+curl -L https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-gnu.tar.gz | tar xz
+sudo mv typst /usr/local/bin/
+```
+
+### Verify Installation
+```bash
+# Check Typst installation
+typst --version
+
+# Test compilation
+typst compile test.typ
+```
+
+### Install Fonts (Optional)
+```bash
+# Install additional fonts for scientific writing
+# Typst includes many fonts by default, but you can add more
+```
+
+## 2. Structure Your Typst Paper
+
+Organize your paper with standard Typst document structure:
+
+### Basic Document Structure
+```typst
+#set document(title: "Your Scientific Paper Title", author: "Your Name")
+#set page(numbering: "1")
+
+= Abstract
+Your abstract goes here. This should provide a brief summary of your research question, methods, and key findings.
+
+= Introduction
+Background information, research objectives, and significance of your work.
+
+= Methods
+Detailed description of your approach, data sources, and analysis methods.
+
+= Results
+Presentation of your findings with tables, figures, and statistical analysis.
+
+= Discussion
+Interpretation of results, implications, and future research directions.
+
+= References
+#bibliography("references.bib")
+```
+
+### Advanced Document Structure
+```typst
+#import "@preview/book:0.2.1": *
+
+#set document(
+  title: "Advanced Scientific Paper Title",
+  author: "Author Name",
+  date: datetime.today(),
+  paper: "a4"
+)
+
+#set page(
+  numbering: "1",
+  margin: (x: 2.5cm, y: 2.5cm)
+)
+
+#set text(
+  font: "New Computer Modern",
+  size: 11pt,
+  line-height: 1.4
+)
+
+#set par(
+  justify: true,
+  first-line-indent: 1em
+)
+
+= Abstract
+Your comprehensive abstract here.
+
+= Introduction
+#label("sec:introduction")
+Background information and research objectives.
+
+= Methods
+#label("sec:methods")
+
+== Data Collection
+#label("subsec:data")
+Detailed description of data collection procedures.
+
+== Analysis
+#label("subsec:analysis")
+Analysis methods and statistical approaches.
+
+= Results
+#label("sec:results")
+Presentation of findings and statistical results.
+
+= Discussion
+#label("sec:discussion")
+Interpretation and implications of results.
+
+= Conclusion
+#label("sec:conclusion")
+Summary and future directions.
+
+= References
+#bibliography("references.bib", style: "apa")
+```
+
+## 3. Write Mathematical Content
+
+Add complex mathematical equations and notation:
+
+### Inline Mathematics
+```typst
+The quadratic equation $ax^2 + bx + c = 0$ has solutions given by the quadratic formula.
+
+The correlation coefficient $r$ ranges from $-1$ to $+1$, where $r = 0$ indicates no correlation.
+
+The p-value threshold $alpha = 0.05$ is commonly used in statistical testing.
+```
+
+### Display Equations
+```typst
+The quadratic formula is:
+$x = (-b +- sqrt(b^2 - 4ac)) / (2a)$
+
+Linear regression model:
+$y = mx + b = 2.5x + 1.2$
+
+Gaussian integral:
+$integral(-infinity, infinity, e^(-x^2) dx) = sqrt(pi)$
+```
+
+### Complex Mathematical Structures
+```typst
+Linear model:
+$f(x) = sum_(i=1)^n w_i x_i + b = bold(w)^T bold(x) + b$
+
+Maxwell's equations:
+${
+  nabla dot bold(E) = rho / epsilon_0 \
+  nabla dot bold(B) = 0 \
+  nabla times bold(E) = -del bold(B) / del t \
+  nabla times bold(B) = mu_0 bold(J) + mu_0 epsilon_0 del bold(E) / del t
+}$
+
+Matrix operations:
+$bold(A) = (a_(i,j))_(i=1)^m_(j=1)^n$
+```
+
+### Mathematical Environments
+```typst
+#align(
+  y &= mx + b \
+  &= 2.5x + 1.2
+)
+
+#equation(
+  x = (-b +- sqrt(b^2 - 4ac)) / (2a)
+) <quadratic>
+
+#theorem(
+  name: "Central Limit Theorem",
+  body: [
+    Let $X_1, X_2, ..., X_n$ be independent and identically distributed random variables with mean $mu$ and variance $sigma^2$. Then:
+    $bar(X_n) = (1/n) sum_(i=1)^n X_i$
+    converges in distribution to $N(mu, sigma^2/n)$ as $n rightarrow infinity$.
+  ]
+)
+```
+
+## 4. Add Tables and Figures
+
+Create professional tables and include figures:
+
+### Professional Tables
+```typst
+#table(
+  caption: "Summary Statistics by Experimental Group",
+  columns: 6,
+  align: center,
+  [*Group*], [*N*], [*Mean*], [*SD*], [*Min*], [*Max*],
+  [Control], [25], [15.2], [2.1], [12.1], [18.9],
+  [Treatment A], [25], [18.7], [2.8], [14.3], [22.1],
+  [Treatment B], [25], [17.3], [2.5], [13.8], [20.5]
+)
+```
+
+### Advanced Tables
+```typst
+#table(
+  caption: "Regression Results",
+  columns: 6,
+  align: center,
+  [*Variable*], [*Coefficient*], [*SE*], [*t-value*], [*p-value*], [*95% CI*],
+  [Intercept], [2.45], [0.31], [7.90], [<0.001], [[1.84, 3.06]],
+  [Age], [0.12], [0.05], [2.40], [0.017], [[0.02, 0.22]],
+  [Gender (Male)], [-0.34], [0.15], [-2.27], [0.024], [[-0.64, -0.04]],
+  [Education], [0.08], [0.03], [2.67], [0.008], [[0.02, 0.14]],
+  [*Note*: $R^2 = 0.23$, $F(3, 196) = 19.45$, $p < 0.001$]
+)
+```
+
+### Including Figures
+```typst
+#figure(
+  image("figures/results_plot.pdf", width: 80%),
+  caption: "Experimental results showing significant differences between groups. Error bars represent standard error of the mean."
+) <fig:results>
+
+#figure(
+  stack(
+    direction: horizontal,
+    spacing: 1em,
+    figure(
+      image("figures/plot_a.pdf", width: 100%),
+      caption: "Control group results"
+    ),
+    figure(
+      image("figures/plot_b.pdf", width: 100%),
+      caption: "Treatment group results"
+    )
+  ),
+  caption: "Comparison of experimental outcomes between control and treatment groups."
+) <fig:comparison>
+```
+
+### Custom Figure Functions
+```typst
+#let scientific-figure(image, caption, label) = {
+  figure(
+    image,
+    caption: caption,
+    numbering: "Figure #counter(figure).",
+  ) <#label>
+}
+
+#scientific-figure(
+  image("figures/experiment.pdf", width: 70%),
+  "Experimental setup and methodology",
+  "fig:experiment"
+)
+```
+
+## 5. Add Citations and References
+
+Include academic citations using Typst's bibliography system:
+
+### Citation Commands
+```typst
+= Literature Review
+
+Recent studies have shown significant progress in this field @jones2023, @brown2022.
+The work by @smith2023 provides a comprehensive framework for understanding these patterns.
+
+Our approach builds upon the methodology described by @wilson2021, extending it to handle 
+larger datasets and more complex experimental conditions.
+
+Multiple studies have demonstrated the effectiveness of this approach @jones2023; @brown2022; @smith2023.
+```
+
+### Bibliography Configuration
+```typst
+#set bibliography(
+  style: "apa",
+  title: "References",
+  numbering: "1."
+)
+
+#bibliography("references.bib")
+```
+
+### BibTeX File
+Create a `references.bib` file:
+```bibtex
+@article{jones2023,
+  title={Recent advances in computational methods for scientific analysis},
+  author={Jones, A. and Wilson, B. and Davis, C.},
+  journal={Nature},
+  year={2023},
+  volume={123},
+  pages={456--789},
+  doi={10.1038/nature12345}
+}
+
+@article{brown2022,
+  title={Novel approaches to data analysis in experimental sciences},
+  author={Brown, C. and Miller, D.},
+  journal={Science},
+  year={2022},
+  volume={456},
+  pages={123--456},
+  doi={10.1126/science.abc1234}
+}
+
+@article{smith2023,
+  title={A comprehensive framework for scientific computing},
+  author={Smith, J. and Johnson, K.},
+  journal={Computational Science},
+  year={2023},
+  volume={78},
+  pages={234--567},
+  doi={10.1016/j.compsci.2023.123456}
+}
+
+@book{wilson2021,
+  title={Advanced Methods in Scientific Research},
+  author={Wilson, R.},
+  year={2021},
+  publisher={Academic Press},
+  address={New York}
+}
+```
+
+## 6. Cross-Reference Content
+
+Link to figures, tables, and sections throughout your paper:
+
+### Cross-References
+```typst
+= Results
+
+Our analysis produced several key visualizations. The main results are shown in @fig:results, 
+and detailed statistics are presented in @tbl:summary_stats.
+
+= Discussion
+
+As shown in @fig:results, the data reveals clear patterns that support our hypothesis.
+The statistical analysis presented in @tbl:summary_stats confirms the significance of these findings.
+
+Our methodology, described in @sec:methods, follows established protocols in the field.
+```
+
+### Automatic Numbering
+```typst
+= Methods
+#label("sec:methods")
+
+Our computational approach follows the methodology described in @subsec:data.
+
+== Data Collection
+#label("subsec:data")
+Detailed description of data collection procedures...
+
+== Analysis
+#label("subsec:analysis")
+Analysis methods build upon the data collection described in @subsec:data.
+```
+
+### Custom Reference Functions
+```typst
+#let ref-fig(label) = "Figure #counter(figure)"
+#let ref-tbl(label) = "Table #counter(table)"
+#let ref-sec(label) = "Section #counter(heading)"
+
+Our results (@ref-fig("results")) show significant differences between groups.
+The statistical analysis (@ref-tbl("summary")) confirms these findings.
+```
+
+## 7. Use Journal Templates
+
+Apply specific journal formatting requirements:
+
+### Journal-Specific Templates
+```typst
+// Nature journal template
+#set document(
+  title: "Your Paper Title",
+  author: "Your Name",
+  paper: "a4"
+)
+
+#set text(font: "New Computer Modern", size: 10pt)
+#set par(justify: true, first-line-indent: 0pt)
+
+// Science journal template
+#set document(
+  title: "Your Paper Title",
+  author: "Your Name",
+  paper: "a4"
+)
+
+#set text(font: "Times New Roman", size: 11pt)
+#set par(justify: true, first-line-indent: 1em)
+```
+
+### Custom Template Setup
+```typst
+#set document(
+  title: "Your Paper Title",
+  author: "Your Name",
+  date: datetime.today(),
+  paper: "a4"
+)
+
+#set page(
+  numbering: "1",
+  margin: (x: 2.5cm, y: 2.5cm)
+)
+
+#set text(
+  font: "New Computer Modern",
+  size: 11pt,
+  line-height: 1.4
+)
+
+#set par(
+  justify: true,
+  first-line-indent: 1em
+)
+
+#set heading(
+  numbering: "1.1",
+  font: "New Computer Modern",
+  weight: "bold"
+)
+
+#set list(
+  indent: 1em,
+  body-indent: 1em
+)
+
+// Journal-specific metadata
+#let journal-name = "Journal of Scientific Research"
+#let volume-number = "42"
+#let issue-number = "3"
+#let article-number = "12345"
+```
+
+### Template Functions
+```typst
+#let journal-header() = {
+  align(center)[
+    #text(weight: "bold", size: 14pt)[#journal-name] \
+    #text(size: 12pt)[Volume #volume-number, Issue #issue-number] \
+    #text(size: 10pt)[Article #article-number]
+  ]
+}
+
+#journal-header()
+```
+
+## 8. Compile and Export
+
+Build your Typst document and export from Curvenote:
+
+### Local Compilation
+```bash
+# Basic compilation
+typst compile your_paper.typ
+
+# Compile with specific output
+typst compile your_paper.typ --output your_paper.pdf
+
+# Watch for changes (development mode)
+typst watch your_paper.typ
+
+# Compile with custom fonts
+typst compile your_paper.typ --font-path /path/to/fonts
+```
+
+### Curvenote Export
+```bash
+# Export to Typst using Curvenote CLI
+curvenote export typst
+
+# Export with specific template
+curvenote export typst --template nature
+
+# Export with custom output name
+curvenote export typst --output my_paper.typ
+```
+
+### Export Configuration
+Create `curvenote.yml`:
+```yaml
+project:
+  title: "My Typst Scientific Paper"
+  description: "Research paper in Typst format"
+  
+  # Typst export settings
+  export:
+    typst:
+      template: article
+      bibliography: references.bib
+      figures: true
+      tables: true
+      
+  # Bibliography settings
+  bibliography:
+    - references.bib
+```
+
+### Advanced Compilation
+```bash
+# Compile with bibliography
+typst compile your_paper.typ
+typst compile your_paper.typ
+
+# Compile with custom template
+typst compile your_paper.typ --root /path/to/templates
+
+# Generate multiple formats
+typst compile your_paper.typ --format pdf
+typst compile your_paper.typ --format png
+```
+
+## Next Steps
+
+- [Add Citations and References →](./citations.md)
+- [Create Interactive Figures →](./figures-and-images.md)
+- [Organize Your Content →](./organize-content.md)
+- [Export to PDF →](../editor/export-pdf.md)
+
+---
+
+💡 **Tip:** Start with a basic Typst structure, then add complexity as needed. Use Curvenote's version control to track changes and collaborate with co-authors.
+
+⚡ **Important: Typst Best Practices**
+
+- **Clean syntax**: Use Typst's modern, readable syntax for better maintainability
+- **Modular organization**: Break large documents into separate files using imports
+- **Version control**: Track changes to your Typst source files
+- **Template compliance**: Follow journal-specific formatting requirements
+- **Bibliography management**: Keep BibTeX files organized and up-to-date
+- **Performance**: Take advantage of Typst's fast compilation times for iterative development
diff --git a/authoring/version-history.md b/authoring/version-history.md
new file mode 100644
index 0000000..35e3734
--- /dev/null
+++ b/authoring/version-history.md
@@ -0,0 +1,109 @@
+---
+title: Track Versions and Drafts
+short_title: Version History
+---
+
+# Track Versions and Drafts
+
+## Quick Start
+Manage version history, track changes, and work with drafts across your Curvenote articles, notebooks, and blocks
+
+Curvenote provides comprehensive version control for all your content. Every article, notebook, and block can be versioned independently, allowing you to track changes, revert to previous versions, and collaborate safely with automatic draft saving and conflict resolution.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content to version
+- Access to the Curvenote editor interface
+- Understanding of draft mode vs. saved versions
+- Content you want to track changes for
+
+## 1. Understand Version Control
+
+**Drafts vs. Versions**: Drafts are temporary working copies, versions are permanent saved states
+
+**Auto-save**: All changes saved locally as you work
+
+**Individual versioning**: Articles, notebooks, and blocks versioned separately
+
+**Collaboration**: Multiple people can work simultaneously with conflict resolution
+
+## 2. Work with Drafts
+
+**Enter Draft Mode**: Click **EDIT** → Yellow ✏️ indicator appears
+
+**Auto-save**: Changes saved automatically as you type
+
+**Status bar**: Green=synced, orange=10+ unsaved changes, red=not synced
+
+**Exit Draft Mode**: **STOP EDITING** (keeps draft) or **SAVE VERSION** (creates new version)
+
+## 3. Save New Versions
+
+**Save article version**: Click **SAVE VERSION** in app bar → Redirected to new version
+
+**Save block version**: Select block → Block Details Panel → **SAVE VERSION**
+
+**Save notebook version**: Click **SAVE VERSION** → Saves all draft blocks/cells
+
+**Version numbering**: Automatically increments (v1, v2, v3, etc.)
+
+## 4. View Version History
+
+**View article versions**: Exit Draft Mode → Block Details Panel → Browse version list
+
+**View block versions**: Select block → Block Details Panel → Click version numbers
+
+**Version information**: Shows date, time, and version number
+
+**Preview versions**: Click version to preview in place of current version
+
+## 5. Switch Between Versions
+
+**Preview first**: Click version number to preview without switching
+
+**Use version**: Click **USE VERSION** button or version ⋮ Options → Use Version
+
+**Clear preview**: Click **CLEAR PREVIEW** to return to current version
+
+**Use latest**: Click **USE LATEST** to return to most recent version
+
+## 6. Handle Collaboration Conflicts
+
+**Stale draft warning**: Appears when someone else saves a version while you're editing
+
+**Warning indicators**: Yellow ✏️ turns red, warning message at top
+
+**Discard stale draft**: Click × icon → **DELETE** → Page reloads automatically
+
+**Re-enter draft mode**: Click **EDIT** to continue working on latest version
+
+**⚠️ Important**: Unsaved changes are lost when discarding stale drafts
+
+## 7. Export from Versions
+
+**Exit draft mode**: Must be in View Mode to export
+
+**Save draft changes**: Click **SAVE VERSION** to include recent changes
+
+**Export saved version**: Click **STOP EDITING** to export without draft changes
+
+**Export formats**: PDF, Word, LaTeX, Markdown from saved versions only
+
+## Next Steps
+
+- [Reuse Content Blocks →](./reuse-blocks.md)
+- [Organize Your Content →](./organize-content.md)
+- [Export Your Work →](../editor/export-pdf.md)
+
+---
+
+💡 **Tip:** Use descriptive version names or save frequently to make it easier to find specific versions later. The status bar at the bottom shows your sync status - keep it green for best performance.
+
+⚡ **Important: Version Control Best Practices**
+
+- **Save frequently**: Create versions regularly to avoid losing work
+- **Check status bar**: Monitor sync status to ensure changes are saved
+- **Handle conflicts**: Always discard stale drafts when warned
+- **Export from versions**: Only saved versions can be exported
+- **Collaborate safely**: Multiple people can edit simultaneously with automatic conflict resolution
diff --git a/cli/authentication.md b/cli/authentication.md
index d63452e..6ad6f9b 100644
--- a/cli/authentication.md
+++ b/cli/authentication.md
@@ -1,72 +1,136 @@
 ---
-title: Authentication
+title: Authentication and API Tokens
 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.
+# Authentication and API Tokens
 
-## 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
+## Quick Start
+Set up authentication to access private Curvenote content, sync projects, and deploy websites using API tokens
 
-Most translation/export of **public content** does not require authentication.
+Most Curvenote CLI functionality works without authentication, but you'll need an API token to access private content, sync projects, or deploy websites. API tokens provide secure, programmatic access to your Curvenote account.
 
-## 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.
+## Before You Start
 
-## 2. Store the Token Locally
-Run:
-```bash
+Make sure you have:
+- A Curvenote account at curvenote.com
+- Access to your account settings
+- The Curvenote CLI installed
+- Terminal or command prompt access
+
+## 1. Understand Authentication Requirements
+
+**Public content**: No authentication required
+
+**Private content**: API token required
+
+**Project sync**: API token required
+
+**Site deployment**: API token required
+
+**Content modification**: API token required
+
+## 2. Create an API Token
+
+Generate a token from your Curvenote account:
+
+**Navigate to**: https://curvenote.com/profile?settings=true&tab=profile-api
+
+**Click**: "Generate New Token"
+
+**Add description**: Use a recognizable name (e.g., "CLI Access")
+
+**Copy token**: Save the token immediately (you won't see it again)
+
+## 3. Set Up CLI Authentication
+
+Configure the CLI with your token:
+
+```shell
 curvenote token set
 ```
-Paste the API token when prompted.
 
-## 3. Store the Token as an Environment Variable
+**Enter your API token** when prompted
 
-Useful for CI/CD or servers:
+**Token is stored** in local configuration file
 
-```bash
-export CURVENOTE_TOKEN="API_TOKEN"
+**No need to re-enter** for future sessions
+
+## 4. Verify Authentication
+
+Check that you're properly authenticated:
+
+```shell
+curvenote auth list
 ```
-The environment variable takes priority over stored tokens.
 
-## 4. Switch Accounts
+**Expected output:**
+```
+Username: your-username
+Email: your-email@example.com
+```
 
-If you have multiple accounts:
+**If not authenticated:**
+```
+You are not authenticated
+```
+
+## 5. Manage Multiple Accounts
+
+Switch between different Curvenote accounts:
 
 ```bash
 curvenote token select
 ```
 
-## 5. Check Authentication Status
-```bash
-curvenote auth list
+**Select account** from the list
+
+**Switch profiles** for different projects
+
+**Useful for**: Team accounts, bot accounts, testing
+
+## 6. Server Authentication
+
+Use environment variables for server deployment:
+
+```shell
+export CURVENOTE_TOKEN="your-api-token"
 ```
-Shows your current account or indicates if not authenticated.
 
-## 6. Sign Out
-```bash
+**GitHub Actions**: Add as repository secret
+
+**CI/CD systems**: Set as environment variable
+
+**Server deployment**: Use environment variable
+
+## 7. Remove Authentication
+
+Sign out of the CLI when needed:
+
+```shell
 curvenote token delete
 ```
 
-Removes the stored token. If using an environment variable, unset it:
-```bash
-unset CURVENOTE_TOKEN
-```
+**Removes local config** file
+
+**Environment variables**: Use `unset CURVENOTE_TOKEN`
+
+**Verify logout**: Run `curvenote auth list`
+
+## Next Steps
+
+- [Learn CLI Commands →](./commands.md)
+- [Create Your First Project →](../Getting Started/create-project.md)
+- [Deploy Your Site →](../quick-start/3-publish.md)
+
+---
+
+💡 **Tip:** Use descriptive names for your API tokens so you can easily identify and manage them later. Consider creating separate tokens for different environments (development, production, CI/CD).
 
-💡 **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.  
+⚡ **Important: Security Best Practices**
 
-## 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)
+- **Keep tokens secure**: Never share API tokens publicly
+- **Use environment variables**: For server deployments and CI/CD
+- **Regular rotation**: Generate new tokens periodically
+- **Limited scope**: Create tokens with minimal required permissions
+- **Monitor usage**: Check token activity in your account settings
diff --git a/cli/commands.md b/cli/commands.md
index 1b37915..fcc825c 100644
--- a/cli/commands.md
+++ b/cli/commands.md
@@ -1,79 +1,185 @@
 ---
-title: Commands
+title: CLI Commands Reference
+short_title: Commands
 ---
 
-This has the list of all commands for the Curvenote CLI, you can use the help `curvenote -h` on any command and this will print the help for the command or service. To see the version of Curvenote, use `curvenote -v`. For debugging, use the `-d` or `--debug` flag and all debug commands will be logged, use this if any commands fail.
+# CLI Commands Reference
 
-## Getting Started
+## Quick Start
+Learn the essential Curvenote CLI commands for creating projects, building content, and deploying websites
 
-These commands are designed with prompts to get you started easily and point you to other information on how to get started.
+The Curvenote CLI provides a comprehensive set of commands for managing scientific content and websites. Use `curvenote --help` to see all available commands and `curvenote <command> --help` for specific command options.
+
+## Before You Start
 
-### curvenote init
+Make sure you have:
+- Curvenote CLI installed and working
+- Basic understanding of command line operations
+- Authentication set up (for private content)
+- A project to work with
+
+## 1. Getting Started Commands
+
+**Initialize new project:**
+```shell
+curvenote init [project-name]
+```
+
+**Clone existing project:**
+```shell
+curvenote clone [remote-url] [folder]
+```
+
+**Get help:**
+```shell
+curvenote --help
+curvenote <command> --help
+```
+
+**Check version:**
+```shell
+curvenote --version
+```
+
+## 2. Local Development Commands
+
+**Start local server:**
+```shell
+curvenote start
+```
+
+**Build content locally:**
+```shell
+curvenote build
+```
+
+**Clean build cache:**
+```shell
+curvenote start --clean
+curvenote build --clean
+```
+
+**Force reinstall dependencies:**
+```shell
+curvenote start --force
+curvenote build --force
+```
+
+## 3. Deployment Commands
+
+**Deploy to web:**
+```shell
+curvenote deploy
+```
+
+**Deploy without prompts:**
+```shell
+curvenote deploy --yes
+```
+
+**Deploy with strict checking:**
+```shell
+curvenote deploy --strict
+```
+
+**Check external links:**
+```shell
+curvenote deploy --check-links
+```
+
+## 4. Content Sync Commands
+
+**Pull content from remote:**
+```shell
+curvenote pull [path]
+```
+
+**Pull without prompts:**
+```shell
+curvenote pull --yes
+```
+
+**Pull specific file:**
+```shell
+curvenote pull content/article.md
+```
+
+## 5. Authentication Commands
+
+**Set API token:**
+```shell
+curvenote token set
+```
+
+**List authenticated accounts:**
+```shell
+curvenote auth list
+```
+
+**Switch between accounts:**
+```shell
+curvenote token select
+```
+
+**Remove authentication:**
+```shell
+curvenote token delete
+```
+
+## 6. Advanced Commands
+
+**Write table of contents:**
+```shell
+curvenote build --write-toc
+```
+
+**Use specific branch:**
+```shell
+curvenote start --branch main
+```
+
+**CI/CD mode:**
+```shell
+curvenote build --ci
+curvenote deploy --ci
+```
+
+**Debug mode:**
+```shell
+curvenote --debug
+```
+
+## 7. Common Flags and Options
+
+**Global flags:**
+- `--help`: Show command help
+- `--version`: Show CLI version
+- `--debug`: Enable debug logging
+
+**Build flags:**
+- `--clean`: Clean build cache
+- `--force`: Force reinstall dependencies
+- `--strict`: Stop on errors
+- `--check-links`: Verify external links
+
+**Deploy flags:**
+- `--yes`: Skip confirmation prompts
+- `--ci`: Skip installation for CI/CD
+
+## Next Steps
+
+- [Set Up Authentication →](./authentication.md)
+- [Create Your First Project →](../Getting Started/create-project.md)
+- [Deploy Your Site →](../quick-start/3-publish.md)
 
-Creates a project from a directory or clones a remote Curvenote project.
-
-- `-y` or `--yes`: Follows the defaults for initializing a project.
-- `--write-toc`: Write an explicit table of contents.
-
-After calling `curvenote init` you will have a local folder with a `curvenote.yml` that defines all site and project settings.
-
-### curvenote clone
-
-Clone a remote Curvenote project, and brings all markdown, notebooks, and site configuration to your local folder.
-
-**Optional arguments**
-
-- `[remote]`: specify the remote project URL, e.g. `https://curvenote.com/@templates/web` if this is not supplied, the CLI will ask you for a remote project URL.
-- `[folder]`: specify the local folder to clone into, must not exist. When paired with `-y` below the folder will be chosen as `content/name` where `name` is the name of the Curvenote project.
-
-**Flags**
-
-- `-y` or `--yes`: Follows the defaults for which local folder to clone to, you must provide a remote.
-
-If you are cloning in a folder that already contains a site, then this command will also add the project to your curvenote `site.projects` list as well as an entry into the navigation.
-
-## Working Locally
-
-### curvenote start
-
-Start a local server that live-reloads when you make changes.
-
-- `-c` or `--clean`: clean all cached content, including images. Clean is called before a `curvenote deploy`.
-- `-f` or `--force`: force re-install all dependencies. Helpful to reset the curvenote web server as well as pull any new changes.
-- `--branch`: Branch to clone from <https://github.com/curvenote/curvenote>. Helpful for testing out new features or in development.
-- `--keep-host`: The `HOST` environment variable is by default `localhost`, and will be changed by default. Setting this flag will allow the `HOST` environment variable to be passed into the web server, and may cause it to crash if it is malformed.
-
-### curvenote build
-
-Build all content locally, this is called by `start` and `deploy`. You can use this to write a table of contents, or check links or any other issues without starting a server.
-
-- `-c` or `--clean`: clean all cached content, including images. Clean is called before a `curvenote deploy`.
-- `-f` or `--force`: force re-install all dependencies. Helpful to reset the curvenote web server as well as pull any new changes.
-- `--branch`: Branch to clone from <https://github.com/curvenote/curvenote>. Helpful for testing out new features or in development.
-- `--write-toc`: Write an explicit table of contents.
-- `-ci`: Skip the installation and just create build folders for deployment. Helpful when working in a continuous integration system, like [deploying from GitHub](./github-action.md).
-- `--strict`: Summarize build warnings and stop on any errors.
-- `--check-links`: Check all links to external websites resolve.
-
-## Deploying
-
-### curvenote deploy
-
-- `-y` or `--yes`: Do not ask if you are sure you want to deploy!
-- `-f` or `--force`: force re-install all dependencies. Helpful to reset the curvenote web server as well as pull any new changes.
-- `-ci`: Skip the installation and just create build folders for deployment. Helpful when working in a continuous integration system, like [deploying from GitHub](./github-action.md).
-- `--strict`: Summarize build warnings and stop on any errors.
-- `--check-links`: Check all links to external websites resolve.
-
-Use the `site.domains` setting in your `curvenote.yml` to configure which site to deploy to.
-
-## Syncing Content
-
-### curvenote pull
+---
 
-Pull content from a remote Curvenote project or document. This command will overwrite any local content.
+💡 **Tip:** Use `curvenote --help` to explore all available commands and `curvenote <command> --help` to see specific options for each command.
 
-- `[path]`: the path to a local project folder or file with a remote configured, if omitted all content will be pulled.
-- `-y` or `--yes`: Do not ask if you want to override the files.
+⚡ **Important: Command Best Practices**
 
-You can pull both an entire project, or a single file.
+- **Use help commands**: Always check `--help` for command options
+- **Test locally first**: Use `curvenote start` before deploying
+- **Use clean builds**: Add `--clean` flag when troubleshooting
+- **Check links**: Use `--check-links` before final deployment
+- **Use CI mode**: Add `--ci` flag for automated deployments
diff --git a/cli/configuration.md b/cli/configuration.md
new file mode 100644
index 0000000..db9dc9a
--- /dev/null
+++ b/cli/configuration.md
@@ -0,0 +1,173 @@
+---
+title: Configure Curvenote Projects
+short_title: Configuration
+---
+
+# Configure Curvenote Projects
+
+## Quick Start
+Configure your Curvenote projects using YAML configuration files to customize site settings, project metadata, and deployment options
+
+Curvenote uses YAML configuration files (`curvenote.yml` or `myst.yml`) to define project settings, site configuration, and deployment options. These files control everything from site appearance to export formats and domain settings.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project initialized
+- Access to edit YAML configuration files
+- Understanding of your project requirements
+- Basic knowledge of YAML syntax
+
+## 1. Understand Configuration Files
+
+Learn about the main configuration files:
+
+**curvenote.yml**: Main project configuration file
+
+**myst.yml**: Alternative configuration file (same format)
+
+**Project settings**: Metadata, authors, keywords, exports
+
+**Site settings**: Domains, navigation, branding, themes
+
+**Build settings**: Templates, plugins, custom directives
+
+## 2. Configure Project Metadata
+
+Set up basic project information:
+
+```yaml
+version: 1
+project:
+  id: your-project-id
+  title: Your Project Title
+  description: Brief project description
+  keywords: [keyword1, keyword2, keyword3]
+  authors:
+    - name: Author Name
+      email: author@example.com
+      orcid: 0000-0000-0000-0000
+      affiliations:
+        - Institution Name
+  github: https://github.com/username/repo
+  copyright: Copyright 2024
+```
+
+## 3. Configure Site Settings
+
+Set up your website configuration:
+
+```yaml
+site:
+  title: Your Site Title
+  domains:
+    - your-site.curve.space
+    - your-custom-domain.com
+  logo: public/logo.svg
+  logo_text: Your Brand
+  nav:
+    - title: Home
+      url: /
+    - title: About
+      url: /about
+  actions:
+    - title: Contact
+      url: /contact
+  twitter: your-handle
+  analytics_google: G-XXXXXXXXXX
+```
+
+## 4. Set Up Table of Contents
+
+Configure your site's navigation structure:
+
+```yaml
+toc:
+  - file: index.md
+  - title: Getting Started
+    children:
+      - file: getting-started/install.md
+      - file: getting-started/first-project.md
+  - title: Documentation
+    children:
+      - file: docs/guide.md
+      - file: docs/reference.md
+```
+
+## 5. Configure Export Options
+
+Set up export formats and templates:
+
+```yaml
+project:
+  exports:
+    - format: pdf
+      template: journal
+    - format: word
+      template: report
+    - format: latex
+      template: article
+    - format: meca
+  requirements:
+    - requirements.txt
+    - environment.yml
+  resources:
+    - data/**/*
+    - figures/**/*
+```
+
+## 6. Set Up Computational Environment
+
+Configure Jupyter and computational settings:
+
+```yaml
+project:
+  jupyter: true
+  requirements:
+    - requirements.txt
+    - apt.txt
+  resources:
+    - src/**/*
+    - data/**/*
+    - models/**/*
+  exports:
+    - format: meca
+```
+
+## 7. Customize Build Settings
+
+Configure build and rendering options:
+
+```yaml
+project:
+  plugins:
+    - directives.mjs
+    - custom-plugin.js
+  abbreviations:
+    CLI: Command Line Interface
+    API: Application Programming Interface
+  toc:
+    name: true
+    numbered: true
+  references:
+    bibliography: references.bib
+    style: apa
+```
+
+## Next Steps
+
+- [Learn CLI Commands →](./commands.md)
+- [Set Up Authentication →](./authentication.md)
+- [Deploy Your Site →](./deployment.md)
+
+---
+
+💡 **Tip:** Use YAML validation tools to check your configuration syntax. Most code editors provide YAML syntax highlighting and validation.
+
+⚡ **Important: Configuration Best Practices**
+
+- **Version control**: Always commit your configuration files to git
+- **Backup configs**: Keep copies of working configurations
+- **Test locally**: Use `curvenote start` to test configuration changes
+- **Incremental changes**: Make small changes and test frequently
+- **Document customizations**: Comment your configuration for team members
diff --git a/cli/deployment.md b/cli/deployment.md
new file mode 100644
index 0000000..58215d9
--- /dev/null
+++ b/cli/deployment.md
@@ -0,0 +1,196 @@
+---
+title: Deploy Curvenote Sites
+short_title: Deployment
+---
+
+# Deploy Curvenote Sites
+
+## Quick Start
+Deploy your Curvenote projects to the web using the CLI for automatic hosting, custom domains, and continuous deployment
+
+Deploy your Curvenote sites to get them online quickly with automatic hosting, custom domain support, and integration with GitHub Actions for continuous deployment.
+
+## Before You Start
+
+Make sure you have:
+- Curvenote CLI installed and authenticated
+- A project ready for deployment
+- Content tested locally with `curvenote start`
+- API token configured for deployment
+
+## 1. Prepare for Deployment
+
+Get your project ready for deployment:
+
+**Test locally:**
+```shell
+curvenote start
+# Verify everything looks correct
+```
+
+**Check for issues:**
+```shell
+curvenote build --strict
+```
+
+**Verify configuration:**
+```shell
+curvenote build --check-links
+```
+
+**Stop local server:**
+```shell
+# Press Ctrl+C to stop
+```
+
+## 2. Deploy to curve.space
+
+Deploy to Curvenote's free hosting:
+
+**Basic deployment:**
+```shell
+curvenote deploy
+```
+
+**Deploy without prompts:**
+```shell
+curvenote deploy --yes
+```
+
+**Deploy with strict checking:**
+```shell
+curvenote deploy --strict
+```
+
+**What happens:**
+- Builds your project
+- Uploads files to curve.space
+- Provides live URL
+
+## 3. Configure Custom Domains
+
+Set up your own domain name:
+
+**Add domain to configuration:**
+```yaml
+site:
+  domains:
+    - your-site.curve.space
+    - your-custom-domain.com
+```
+
+**Set up DNS records:**
+- **CNAME record**: Point to `ssh.curve.space`
+- **A record**: Point to Curvenote's IP (if provided)
+
+**Contact support:**
+Email support@curvenote.com with your domain
+
+**Wait for activation** (usually 24 hours)
+
+## 4. Set Up GitHub Actions
+
+Automate deployment with GitHub:
+
+**Create workflow file:**
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: curvenote/action-deploy@v1
+        env:
+          CURVENOTE_TOKEN: ${{ secrets.CURVENOTE_TOKEN }}
+```
+
+**Add repository secret:**
+- Go to repository Settings → Secrets
+- Add `CURVENOTE_TOKEN` with your API token
+
+**Push to trigger deployment**
+
+## 5. Manage Multiple Deployments
+
+Deploy to different environments:
+
+**Development deployment:**
+```shell
+curvenote deploy --branch dev
+```
+
+**Production deployment:**
+```shell
+curvenote deploy --branch main
+```
+
+**Preview deployment:**
+```shell
+curvenote deploy --preview
+```
+
+## 6. Monitor Deployment Status
+
+Check your deployment status:
+
+**View deployment logs:**
+```shell
+curvenote deploy --verbose
+```
+
+**Check site status:**
+Visit your deployed URL
+
+**Monitor GitHub Actions:**
+Check Actions tab in your repository
+
+**Verify content:**
+Ensure all files deployed correctly
+
+## 7. Troubleshoot Deployment
+
+Resolve common deployment issues:
+
+**Build errors:**
+```shell
+curvenote build --strict
+```
+
+**Authentication issues:**
+```shell
+curvenote auth list
+curvenote token set
+```
+
+**Network issues:**
+```shell
+curvenote deploy --retry
+```
+
+**Cache issues:**
+```shell
+curvenote deploy --clean
+```
+
+## Next Steps
+
+- [Learn CLI Commands →](./commands.md)
+- [Configure Your Project →](./configuration.md)
+- [Set Up GitHub Actions →](./integration.md)
+
+---
+
+💡 **Tip:** Always test your site locally with `curvenote start` before deploying to catch any issues early.
+
+⚡ **Important: Deployment Best Practices**
+
+- **Test locally first**: Use `curvenote start` before every deployment
+- **Use version control**: Commit your changes before deploying
+- **Check links**: Use `--check-links` flag to verify external links
+- **Monitor deployments**: Check your site after deployment
+- **Use CI/CD**: Set up GitHub Actions for automated deployment
diff --git a/cli/export.md b/cli/export.md
new file mode 100644
index 0000000..073dc00
--- /dev/null
+++ b/cli/export.md
@@ -0,0 +1,199 @@
+---
+title: Export Curvenote Content
+short_title: Export
+---
+
+# Export Curvenote Content
+
+## Quick Start
+Export your Curvenote projects to various formats including PDF, Word, LaTeX, and MECA archives for sharing and publication
+
+Export your Curvenote content to different formats for sharing, publication, or archival purposes. The CLI supports multiple export formats with customizable templates and options.
+
+## Before You Start
+
+Make sure you have:
+- Curvenote CLI installed and working
+- A project with content to export
+- Content tested locally with `curvenote start`
+- Understanding of your target format requirements
+
+## 1. Understand Export Formats
+
+Learn about available export options:
+
+**PDF**: Professional documents with LaTeX templates
+
+**Word**: Microsoft Word documents (.docx)
+
+**LaTeX**: Source files for LaTeX compilation
+
+**MECA**: Reproducible research archives
+
+**Markdown**: Plain markdown files
+
+**HTML**: Static website files
+
+## 2. Export to PDF
+
+Create professional PDF documents:
+
+**Basic PDF export:**
+```shell
+curvenote export pdf
+```
+
+**Export with specific template:**
+```shell
+curvenote export pdf --template journal
+```
+
+**Export with custom options:**
+```shell
+curvenote export pdf --template article --output my-paper.pdf
+```
+
+**Available templates:**
+- journal, article, report, thesis, book
+
+## 3. Export to Word
+
+Create Microsoft Word documents:
+
+**Basic Word export:**
+```shell
+curvenote export word
+```
+
+**Export with template:**
+```shell
+curvenote export word --template report
+```
+
+**Export specific file:**
+```shell
+curvenote export word content/article.md
+```
+
+**Word templates:**
+- report, article, letter, memo
+
+## 4. Export to LaTeX
+
+Generate LaTeX source files:
+
+**Basic LaTeX export:**
+```shell
+curvenote export latex
+```
+
+**Export with template:**
+```shell
+curvenote export latex --template article
+```
+
+**Export with custom options:**
+```shell
+curvenote export latex --template journal --output paper.tex
+```
+
+**LaTeX templates:**
+- article, journal, report, book, thesis
+
+## 5. Export MECA Archives
+
+Create reproducible research archives:
+
+**Export MECA archive:**
+```shell
+curvenote export meca
+```
+
+**Include computational environment:**
+```yaml
+project:
+  jupyter: true
+  requirements:
+    - requirements.txt
+  resources:
+    - data/**/*
+    - src/**/*
+  exports:
+    - format: meca
+```
+
+**MECA includes:**
+- All source files
+- Computational environment
+- Data and resources
+- Metadata and citations
+
+## 6. Configure Export Settings
+
+Customize export options in your configuration:
+
+**Set up export formats:**
+```yaml
+project:
+  exports:
+    - format: pdf
+      template: journal
+    - format: word
+      template: report
+    - format: latex
+      template: article
+    - format: meca
+```
+
+**Configure templates:**
+```yaml
+project:
+  exports:
+    - format: pdf
+      template: journal
+      options:
+        geometry: margin=1in
+        fontsize: 11pt
+```
+
+## 7. Manage Export Output
+
+Organize and find your exports:
+
+**Default export location:**
+```
+_build/exports/
+```
+
+**List export files:**
+```shell
+ls _build/exports/
+```
+
+**Custom output directory:**
+```shell
+curvenote export pdf --output ./exports/
+```
+
+**Export specific content:**
+```shell
+curvenote export pdf content/chapter1.md
+```
+
+## Next Steps
+
+- [Learn CLI Commands →](./commands.md)
+- [Configure Your Project →](./configuration.md)
+- [Deploy Your Site →](./deployment.md)
+
+---
+
+💡 **Tip:** Use the `--template` option to match your target publication format. Different templates provide different styling and formatting options.
+
+⚡ **Important: Export Best Practices**
+
+- **Test locally first**: Use `curvenote start` to preview content
+- **Check templates**: Verify template compatibility with your content
+- **Include metadata**: Ensure proper author and citation information
+- **Test exports**: Verify exported files open correctly
+- **Backup exports**: Keep copies of important exported files
diff --git a/cli/index.md b/cli/index.md
index 9edc6c1..cdf51aa 100644
--- a/cli/index.md
+++ b/cli/index.md
@@ -3,32 +3,103 @@ title: Curvenote CLI Overview
 short_title: Overview
 ---
 
-`curvenote` is a command line interface (CLI) that provides modern tooling for technical writing, reproducible science, and creating scientific & technical websites. To get started install curvenote:
+# Curvenote CLI Overview
+
+## Quick Start
+Install and use the Curvenote command line interface to create, manage, and deploy scientific content and websites
+
+The Curvenote CLI provides modern tooling for technical writing, reproducible science, and creating scientific & technical websites. It enables local content transformations, collaborative writing workflows, and seamless deployment to the web.
+
+## Before You Start
+
+Make sure you have:
+- Node.js version 14 or higher installed
+- Access to a terminal or command prompt
+- Understanding of basic command line operations
+- A Curvenote account (for authentication features)
+
+## 1. Install the CLI
+
+Get the Curvenote CLI tool:
 
 ```shell
 npm install -g curvenote
 ```
 
-See [Installing Curvenote](./installing.md) for more details, you must have a node version greater than 14 (see [Installing NodeJS](./installing-prerequisites.md) for more information).
+**Verify installation:**
+```shell
+curvenote --version
+```
+
+**Get help:**
+```shell
+curvenote --help
+```
 
-The CLI and all dependencies made by Curvenote are [open-source](https://github.com/curvenote/curvenote) (MIT License) and we contribute to upstream projects where we can (e.g. our founders are members of [Executable Books](https://executablebooks.org/en/latest/team.html)). The Curvenote CLI provides local content transformations, with an early focus on providing 100s of [LaTeX templates](https://github.com/curvenote/templates) for various scientific journals. The library also provides a connection to sync your local documents with Curvenote to aid in collaborative writing, especially in bridging the gap between those who can use Markdown, Git, and a Shell and those of us who are not programmers. We think this is especially important for writing workflows, where the collaboration and communication process is often quite different than a Git-driven approach.
+## 2. Understand CLI Capabilities
 
-```{figure} images/curvenote-start.png
-:align: center
-:width: 70%
+The Curvenote CLI provides comprehensive tools for:
 
-Get started with a `curvenote init` to quickly see your content rendered.
-```
+**Content Creation**: Create and edit scientific & technical websites, including Jupyter Notebooks
+
+**Local Development**: Build and preview content locally with live reload
+
+**Content Sync**: Sync articles and notebooks from Curvenote platform
+
+**Export Options**: Export to PDF, Word, LaTeX, and MyST Markdown formats
+
+**Deployment**: Deploy sites to curve.space or custom domains
+
+## 3. Key CLI Features
+
+**Open Source**: MIT License, available on [GitHub](https://github.com/curvenote/curvenote)
 
-## Features of the Curvenote CLI
+**LaTeX Templates**: 100s of templates for various scientific journals
 
-- Create and edit scientific & technical websites, including Jupyter Notebooks
-- Sync articles and notebooks from Curvenote
-- Locally export to static documents
-- Export to MyST Markdown (see [mystmd.org](https://mystmd.org))
+**Collaborative Workflows**: Bridge gap between technical and non-technical users
+
+**Local Processing**: All content transformations happen locally
+
+**Version Control**: Integrates with Git for collaborative development
+
+## 4. Basic Workflow
+
+**Initialize project**: `curvenote init` to create new projects
+
+**Start development**: `curvenote start` for local preview
+
+**Build content**: `curvenote build` to process content
+
+**Deploy site**: `curvenote deploy` to publish online
+
+**Sync content**: `curvenote pull` to get latest changes
+
+## 5. Integration Options
+
+**GitHub Actions**: Automated deployment and previews
+
+**Jupyter Integration**: Direct notebook support and execution
+
+**MyST Markdown**: Full support for scientific document features
+
+**Custom Domains**: Deploy to your own domain names
+
+**API Access**: Programmatic access to Curvenote features
+
+## Next Steps
+
+- [Install Curvenote CLI →](./installing.md)
+- [Set Up Authentication →](./authentication.md)
+- [Learn Commands →](./commands.md)
+
+---
 
-## Open Source
+💡 **Tip:** Start with `curvenote init` to quickly create a new project and see your content rendered locally. The CLI provides immediate feedback and live previews as you work.
 
-The CLI is Open Source (MIT License) and can be found [on GitHub](https://github.com/curvenote/curvenote). We welcome contributions and [issues](https://github.com/curvenote/curvenote/issues) from anyone looking to improve scientific communication!
+⚡ **Important: CLI Best Practices**
 
-- <https://github.com/curvenote/curvenote>
+- **Keep CLI updated**: Use `npm update -g curvenote` regularly
+- **Use local preview**: Always test with `curvenote start` before deploying
+- **Version control**: Commit your `curvenote.yml` configuration files
+- **Authentication**: Set up API tokens for private content access
+- **Documentation**: Check `curvenote --help` for command options
diff --git a/cli/installing-prerequisites.md b/cli/installing-prerequisites.md
index b11df1c..292b3b2 100644
--- a/cli/installing-prerequisites.md
+++ b/cli/installing-prerequisites.md
@@ -1,116 +1,141 @@
 ---
-title: Installing NodeJS
+title: Install Node.js Prerequisites
+short_title: Node.js Setup
 ---
 
-The Curvenote Command Line Interface (CLI) is built on [NodeJS](https://nodejs.org/en/about/) (`nodejs`), a Javascript runtime that is widely used in many projects including well-known Python projects such as Jupyter Lab. `node` comes with its own package manager called `npm`.
+# Install Node.js Prerequisites
 
-There are a number of ways to install `nodejs` and you can choose one that is suitable depending on your platform and preferences.
+## Quick Start
+Install Node.js version 14 or higher to use the Curvenote CLI for creating and managing scientific content
 
-:::{important} Node Versions
-Curvenote currently supports `nodejs` v16, v18, and v20. Note that odd-numbered releases of `nodejs` are not long-lived and you should prefer even-numbered releases when installing.
-:::
+Node.js is the JavaScript runtime required to run the Curvenote CLI. Choose the installation method that best fits your system and workflow preferences.
 
-Following any of the install methods below, verify your installation and ensure that `node` and `npm` are available on your system _PATH_ by opening a new terminal window or command line prompt and typing:
+## Before You Start
 
-```text
-% node -v
-v22.12.0
-% npm -v
-11.3.0
-```
+Make sure you have:
+- Administrative access to your system (for global installation)
+- Stable internet connection for download
+- Understanding of your system's package manager
+- Terminal or command prompt access
+
+## 1. Choose Installation Method
+
+Select the best method for your system:
 
-## Manual Installation (all platforms)
+**Manual Installation**: Download from nodejs.org (all platforms)
 
-You can download an appropriate installer package for your platform by visiting <https://nodejs.org/>. _LTS_ refers to the current _Long Term Support_ version of `nodejs` and is the best choice for use with Curvenote.
+**Package Managers**: Use system package managers (recommended)
 
-Download the installer package, and follow instructions to execute the installer for your platform. The installer will automatically add `node` and `npm` to your system PATH.
+**Version Managers**: Use nvm or similar tools (advanced users)
 
-🛠️ Next, up [Installing Curvenote](./installing.md)
+**Virtual Environments**: Use conda or nodeenv (isolated environments)
 
-## `node` via `conda` / `mamba` (all platforms)
+## 2. Manual Installation
 
-`nodejs` is available as a package on `conda-forge`, although a limited number of versions are available on that channel. If you are a `conda` user, installation is straightforward but please note that curvenote requires even-numbered node versions, and odd-numbered releases can be found on `conda-forge`.
+Download and install from the official website:
 
-🛠️ Use the following command can be used to lock down the version you are installing, adjust as necessary for the even-numbered version you are targeting:
+**Visit**: https://nodejs.org/
 
-```python
-(my-conda-env)% conda install -c conda-forge 'nodejs>=18,<19'
-(my-conda-env)% node -v
-(my-conda-env)% v16.14.2
-(my-conda-env)% npm -v
-(my-conda-env)% v
+**Download**: LTS (Long Term Support) version
+
+**Install**: Follow platform-specific instructions
+
+**Verify installation:**
+```shell
+node --version
+npm --version
 ```
 
-💡 Alternatively, you can create a new `conda` environment directly as a `node` environment:
+## 3. Package Manager Installation
 
+**macOS (Homebrew):**
 ```shell
-% conda create -yn my-node-env 'nodejs>=18,<19'
-% ....
-#
-# To activate this environment, use
-#
-#     $ conda activate my-node-env
-#
-# To deactivate an active environment, use
-#
-#     $ conda deactivate
+brew install node
 ```
 
-🛠️ Next, up [Installing Curvenote](./installing.md)
+**Ubuntu/Debian:**
+```shell
+sudo apt update
+sudo apt install nodejs npm
+```
 
-## `nodeenv` via pip (all platforms)
+**Windows (Chocolatey):**
+```shell
+choco install nodejs
+```
 
-`nodeenv` is a python package allowing you to create and manage `node` installations on your system via virtual environments. If you want to work in virtual environments for `node` alongside your python `virtualenv` this is the way to go.
+**CentOS/RHEL:**
+```shell
+sudo yum install nodejs npm
+```
 
-🛠️ Install `nodeenv`:
+## 4. Version Manager Installation
 
-```python
-% pip install nodeenv
+**nvm (Linux/macOS):**
+```shell
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 18
+nvm use 18
 ```
 
-🛠️ Query available node versions:
+**nvm-windows:**
+Download from https://github.com/coreybutler/nvm-windows
 
-```python
-% nodeenv --list
-% ... 16.15.0 ...
+**Install specific version:**
+```shell
+nvm install 18.17.0
+nvm use 18.17.0
 ```
 
-🛠️ Create a new environment based on a specific `node` version, and activate it:
+## 5. Virtual Environment Installation
 
+**Conda/Mamba:**
 ```shell
-% nodeenv -n 16.15.0 node_env
-% . node_env/bin/activate
-(node_env) % node -v
-(node_env) % v16.15.0
-(node_env) % npm -v
-(node_env) % v8.5.5
+conda install -c conda-forge 'nodejs>=18,<19'
 ```
 
-Read more about `nodeenv` in [their docs](https://ekalinin.github.io/nodeenv/).
+**nodeenv (Python users):**
+```shell
+pip install nodeenv
+nodeenv -n 18.17.0 my_env
+source my_env/bin/activate
+```
 
-🛠️ Next, up [Installing Curvenote](./installing.md)
+## 6. Verify Installation
 
-## Node Version Manager - Linux/MacOS (`nvm`)
+Test that Node.js is properly installed:
 
-`nvm` is a convenient way to manage multiple node installations on a POSIX compatible system.
+```shell
+node --version
+npm --version
+```
 
-🛠️ Install `nvm` using the install script in [their docs](https://github.com/nvm-sh/nvm).
+**Expected output:**
+```
+v18.17.0
+9.6.7
+```
 
+**Check PATH:**
 ```shell
-% nvm -v
-0.39.1
+which node
+which npm
 ```
 
-💡 Note: on MacOS you can also install `nvm` via `brew`
+## Next Steps
 
-🛠️ Next, install an initial (default) version of `node`:
+- [Install Curvenote CLI →](./installing.md)
+- [Set Up Authentication →](./authentication.md)
+- [Create Your First Project →](../Getting Started/create-project.md)
 
-```bash
-% nvm install 18
-Downloading and installing node v18...
-...
-Now using node v18 (npm v9)
-%
-```
+---
+
+💡 **Tip:** Use the LTS (Long Term Support) version of Node.js for the most stable experience. Even-numbered versions (16, 18, 20) are recommended.
+
+⚡ **Important: Node.js Requirements**
 
-🛠️ Next, up [Installing Curvenote](./installing.md)
+- **Version requirement**: Node.js 14.0.0 or higher
+- **npm requirement**: npm 6.0.0 or higher
+- **LTS versions**: Use even-numbered releases (16, 18, 20)
+- **PATH setup**: Ensure node and npm are in your system PATH
+- **Permissions**: May need sudo/admin access for global installation
diff --git a/cli/installing.md b/cli/installing.md
index 32e714c..bd8d9d1 100644
--- a/cli/installing.md
+++ b/cli/installing.md
@@ -1,37 +1,114 @@
 ---
-title: Installing Curvenote
+title: Install Curvenote CLI
+short_title: Install CLI
 ---
 
-Curvenote is available through [NodeJS](./installing-prerequisites.md) and the node package manager, `npm`. Node is used by Jupyter as well as many other Python packages so you may already have it installed on your _PATH_ and the following command may just work 🤞.
+# Install Curvenote CLI
 
-🛠️ [Install NodeJS](./installing-prerequisites.md) and run the following command:
+## Quick Start
+Install the Curvenote CLI globally using npm to access command line tools for creating and managing scientific content
+
+The Curvenote CLI is distributed through npm and requires Node.js. Once installed, you can create projects, build content, and deploy sites directly from your terminal.
+
+## Before You Start
+
+Make sure you have:
+- Node.js version 14 or higher installed
+- npm (comes with Node.js)
+- Access to a terminal or command prompt
+- Stable internet connection for download
+
+## 1. Check Node.js Installation
+
+Verify Node.js is installed and up to date:
+
+```shell
+node --version
+npm --version
+```
+
+**Required versions:**
+- Node.js: 14.0.0 or higher
+- npm: 6.0.0 or higher
+
+## 2. Install Curvenote CLI
+
+Install the CLI globally:
 
 ```shell
 npm install -g curvenote
 ```
 
-:::{important}
-If you do not have `npm` installed you can look at our guide for [Installing NodeJS](./installing-prerequisites.md). If you have any challenges installing, please [open an issue here](https://github.com/curvenote/curvenotejs/issues) or send an email to [support@curvenote.com](mailto:support@curvenote.com).
-:::
+**What happens:**
+- Downloads and installs Curvenote CLI
+- Adds `curvenote` command to your PATH
+- Installs all required dependencies
+
+## 3. Verify Installation
 
-This will install `curvenote` globally (`-g`) on your system and add a link to the main CLI tool. To see if things worked, try checking the version with:
+Test that the CLI is working:
 
 ```shell
 curvenote --version
 ```
 
-This command should print the current version of the package. If all is good, you can type `curvenote` again in your terminal and it will list the help with all of the options available to you.
+**Expected output:**
+```
+curvenote v2.x.x
+```
 
-:::{note}
-If you have any challenges installing, please [open an issue here](https://github.com/curvenote/curvenote/issues).
-:::
+**Get help:**
+```shell
+curvenote --help
+```
 
-## Updating Curvenote
+## 4. Update Curvenote CLI
 
-There are new releases of the CLI every few weeks, to update to the latest version of `curvenote`, use:
+Keep your CLI up to date:
 
 ```shell
 npm update -g curvenote
 ```
 
-Try the `curvenote --version` command before and after, with an update you should be on the most up to date version (see [npm](https://npmjs.com/package/curvenote) for the latest version!). If you are not, try `npm uninstall -g curvenote` or without the `-g` global flag, until `curvenote` is no longer available on your command line. Then try installing again!
+**When to update:**
+- New features are released
+- Bug fixes are available
+- Security updates are published
+
+## 5. Troubleshoot Installation
+
+**If installation fails:**
+
+**Permission errors:**
+```shell
+sudo npm install -g curvenote
+```
+
+**Clear npm cache:**
+```shell
+npm cache clean --force
+```
+
+**Reinstall completely:**
+```shell
+npm uninstall -g curvenote
+npm install -g curvenote
+```
+
+## Next Steps
+
+- [Set Up Authentication →](./authentication.md)
+- [Learn Basic Commands →](./commands.md)
+- [Create Your First Project →](../Getting Started/create-project.md)
+
+---
+
+💡 **Tip:** Use `npm list -g curvenote` to check your current version and `npm outdated -g` to see if updates are available.
+
+⚡ **Important: Installation Best Practices**
+
+- **Use global installation**: The `-g` flag makes curvenote available system-wide
+- **Keep Node.js updated**: Ensure you have the latest LTS version
+- **Check permissions**: Use `sudo` if you encounter permission errors
+- **Verify installation**: Always test with `curvenote --version` after installation
+- **Regular updates**: Update the CLI regularly for new features and security patches
diff --git a/cli/troubleshooting.md b/cli/troubleshooting.md
new file mode 100644
index 0000000..f07571d
--- /dev/null
+++ b/cli/troubleshooting.md
@@ -0,0 +1,221 @@
+---
+title: Troubleshoot CLI Issues
+short_title: Troubleshooting
+---
+
+# Troubleshoot CLI Issues
+
+## Quick Start
+Resolve common Curvenote CLI issues with step-by-step solutions for installation, authentication, deployment, and build problems
+
+The Curvenote CLI is designed to be reliable, but you may encounter issues during installation, development, or deployment. This guide provides solutions for the most common problems.
+
+## Before You Start
+
+Make sure you have:
+- Basic understanding of command line operations
+- Access to terminal or command prompt
+- Internet connection for downloads
+- Administrative access (if needed)
+
+## 1. Installation Issues
+
+Resolve CLI installation problems:
+
+**Permission errors:**
+```shell
+sudo npm install -g curvenote
+```
+
+**Node.js version issues:**
+```shell
+node --version
+# Should be 14.0.0 or higher
+```
+
+**Clear npm cache:**
+```shell
+npm cache clean --force
+npm install -g curvenote
+```
+
+**Reinstall completely:**
+```shell
+npm uninstall -g curvenote
+npm install -g curvenote
+```
+
+## 2. Authentication Problems
+
+Fix authentication and API token issues:
+
+**Check authentication status:**
+```shell
+curvenote auth list
+```
+
+**Reset API token:**
+```shell
+curvenote token delete
+curvenote token set
+```
+
+**Environment variable issues:**
+```shell
+echo $CURVENOTE_TOKEN
+unset CURVENOTE_TOKEN
+export CURVENOTE_TOKEN="your-token"
+```
+
+**Token permissions:**
+- Verify token has correct permissions
+- Generate new token if needed
+- Check token hasn't expired
+
+## 3. Build and Start Issues
+
+Resolve local development problems:
+
+**Clean build cache:**
+```shell
+curvenote start --clean
+curvenote build --clean
+```
+
+**Force reinstall dependencies:**
+```shell
+curvenote start --force
+curvenote build --force
+```
+
+**Port conflicts:**
+```shell
+# Check what's using port 3000
+lsof -i :3000
+# Kill process or use different port
+```
+
+**Memory issues:**
+```shell
+# Increase Node.js memory limit
+export NODE_OPTIONS="--max-old-space-size=4096"
+curvenote start
+```
+
+## 4. Deployment Issues
+
+Fix deployment problems:
+
+**Build errors before deployment:**
+```shell
+curvenote build --strict
+```
+
+**Network connectivity:**
+```shell
+# Check internet connection
+ping curvenote.com
+```
+
+**Authentication for deployment:**
+```shell
+curvenote auth list
+curvenote token set
+```
+
+**Domain configuration:**
+- Verify domain in `curvenote.yml`
+- Check DNS settings
+- Contact support if needed
+
+## 5. Configuration Issues
+
+Resolve configuration problems:
+
+**YAML syntax errors:**
+```shell
+# Validate YAML syntax
+yamllint curvenote.yml
+```
+
+**Missing configuration:**
+```shell
+# Reinitialize project
+curvenote init
+```
+
+**Template issues:**
+```shell
+# Check template availability
+curvenote export pdf --help
+```
+
+**Plugin problems:**
+- Verify plugin syntax
+- Check plugin compatibility
+- Remove problematic plugins
+
+## 6. Content and Link Issues
+
+Fix content-related problems:
+
+**Broken links:**
+```shell
+curvenote build --check-links
+```
+
+**Missing files:**
+```shell
+# Check file paths
+ls content/
+find . -name "*.md"
+```
+
+**Image loading issues:**
+- Verify image file paths
+- Check image file formats
+- Ensure images are in correct directories
+
+**Citation problems:**
+- Verify BibTeX file syntax
+- Check citation keys
+- Ensure bibliography file is included
+
+## 7. Performance Issues
+
+Improve CLI performance:
+
+**Slow builds:**
+```shell
+# Clean cache and rebuild
+curvenote build --clean
+```
+
+**Memory usage:**
+```shell
+# Monitor memory usage
+top -p $(pgrep node)
+```
+
+**Large projects:**
+- Split into smaller projects
+- Use selective builds
+- Optimize image sizes
+
+## Next Steps
+
+- [Learn CLI Commands →](./commands.md)
+- [Get Support →](./support.md)
+- [Check Documentation →](./reference.md)
+
+---
+
+💡 **Tip:** Use the `--debug` flag to get detailed error information: `curvenote --debug <command>`
+
+⚡ **Important: Troubleshooting Best Practices**
+
+- **Check logs first**: Use `--debug` flag for detailed error information
+- **Clean builds**: Use `--clean` flag when troubleshooting build issues
+- **Verify versions**: Ensure Node.js and CLI versions are compatible
+- **Test incrementally**: Make small changes and test frequently
+- **Document issues**: Keep notes of solutions for future reference
diff --git a/cli/workflows.md b/cli/workflows.md
new file mode 100644
index 0000000..b69d5a9
--- /dev/null
+++ b/cli/workflows.md
@@ -0,0 +1,207 @@
+---
+title: CLI Workflows and Development
+short_title: Workflows
+---
+
+# CLI Workflows and Development
+
+## Quick Start
+Learn common Curvenote CLI workflows for local development, content management, and deployment processes
+
+The Curvenote CLI supports various workflows for different use cases. Whether you're developing locally, collaborating with teams, or deploying to production, these workflows help you work efficiently and maintain consistency.
+
+## Before You Start
+
+Make sure you have:
+- Curvenote CLI installed and configured
+- Authentication set up (for private content)
+- Basic understanding of command line operations
+- A project to work with
+
+## 1. Local Development Workflow
+
+Develop and preview content locally:
+
+**Initialize project:**
+```shell
+curvenote init my-project
+cd my-project
+```
+
+**Start local development:**
+```shell
+curvenote start
+```
+
+**Make changes** to your content files
+
+**Preview automatically** - changes appear in browser
+
+**Stop development:**
+```shell
+# Press Ctrl+C to stop server
+```
+
+## 2. Content Management Workflow
+
+Manage and organize your content:
+
+**Create new content:**
+```shell
+# Add new markdown files to content/
+touch content/new-article.md
+```
+
+**Update table of contents:**
+```shell
+curvenote build --write-toc
+```
+
+**Pull latest changes:**
+```shell
+curvenote pull
+```
+
+**Check for issues:**
+```shell
+curvenote build --strict
+```
+
+## 3. Deployment Workflow
+
+Deploy your site to production:
+
+**Test locally first:**
+```shell
+curvenote start
+# Check everything looks correct
+```
+
+**Build for deployment:**
+```shell
+curvenote build --clean
+```
+
+**Deploy to web:**
+```shell
+curvenote deploy
+```
+
+**Verify deployment:**
+Visit your site URL to confirm changes
+
+## 4. Collaborative Workflow
+
+Work with team members:
+
+**Clone shared project:**
+```shell
+curvenote clone https://curvenote.com/@team/project
+```
+
+**Pull latest changes:**
+```shell
+curvenote pull
+```
+
+**Make your changes** locally
+
+**Test changes:**
+```shell
+curvenote start
+```
+
+**Deploy updates:**
+```shell
+curvenote deploy
+```
+
+## 5. CI/CD Workflow
+
+Automate deployment with GitHub Actions:
+
+**Set up GitHub repository** with your project
+
+**Add GitHub Action:**
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: curvenote/action-deploy@v1
+        env:
+          CURVENOTE_TOKEN: ${{ secrets.CURVENOTE_TOKEN }}
+```
+
+**Push changes** to trigger automatic deployment
+
+## 6. Export Workflow
+
+Export content to different formats:
+
+**Export to PDF:**
+```shell
+curvenote export pdf
+```
+
+**Export to Word:**
+```shell
+curvenote export word
+```
+
+**Export to LaTeX:**
+```shell
+curvenote export latex
+```
+
+**Export MECA archive:**
+```shell
+curvenote export meca
+```
+
+## 7. Troubleshooting Workflow
+
+Resolve common issues:
+
+**Clean build cache:**
+```shell
+curvenote start --clean
+```
+
+**Force reinstall dependencies:**
+```shell
+curvenote start --force
+```
+
+**Check for errors:**
+```shell
+curvenote build --strict
+```
+
+**Verify configuration:**
+```shell
+curvenote build --check-links
+```
+
+## Next Steps
+
+- [Learn CLI Commands →](./commands.md)
+- [Configure Your Project →](./configuration.md)
+- [Set Up Authentication →](./authentication.md)
+
+---
+
+💡 **Tip:** Use `curvenote start` frequently during development to catch issues early. The live reload feature makes it easy to see changes immediately.
+
+⚡ **Important: Workflow Best Practices**
+
+- **Test locally first**: Always use `curvenote start` before deploying
+- **Use version control**: Commit your changes regularly
+- **Clean builds**: Use `--clean` flag when troubleshooting
+- **Check links**: Use `--check-links` before final deployment
+- **Backup regularly**: Keep copies of working configurations
diff --git a/editor/authors.md b/editor/authors.md
deleted file mode 100644
index d21620e..0000000
--- a/editor/authors.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: Adding Authors
----
-
-Search for authors by their user name or create them directly and add additional metadata. Edit the authors ORCID, corresponding email, affiliation(s), and the various contributor roles ([CRediT Roles](https://casrai.org/credit/)). These are used when building various PDF and Word exports across any template.
-
-```{figure} images/Z1isOjJQGvM22q5fhunb-ssL7lufk409dGJ2Qb6r0-v1.mp4
-:name: FVcx77ottY
-:align: center
-:width: 70%
-```
-
-## Editing Authors
-
-You can add or edit authors for an article when you are in edit mode, and click anywhere on the author list.
-
-```{figure} images/Z1isOjJQGvM22q5fhunb-AM3aJvN6YUkQPRoZWoRg-v1.png
-:name: IGpi9HPRiK
-:align: center
-:width: 40%
-```
-
-```{warning}
-Adding an author to your article does not add them as a collaborator to the project!
-
-```
-
-## Affiliations
-
-Author affiliations are saved to your project, so those can be edited or updated in a single place. You will see the “Edit Affiliations” button when adding a new author’s affiliations.
-
-```{figure} images/Z1isOjJQGvM22q5fhunb-UjRFdgVs5OTnZQApy2Yx-v1.png
-:name: IXfdlO26Za
-:align: center
-:width: 70%
-```
-
-To add multiple affiliations, select the affiliation using arrow keys or your mouse and then use the input to continue to type and search for the next affiliation that the author is associated with.
diff --git a/editor/citations.md b/editor/citations.md
deleted file mode 100644
index b20e3ae..0000000
--- a/editor/citations.md
+++ /dev/null
@@ -1,135 +0,0 @@
----
-title: Add Citations and References
-short_title: Citations
----
-
-# Add Citations and References
-
-## Quick Start
-Add citations to your Curvenote articles using DOIs or BibTeX files with automatic formatting and reference management
-
-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.
-
-## Before You Start
-
-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
-
-## Video Demo 📺
-
-[Watch the video tutorial](https://www.loom.com/embed/646329caf1e74c39bd6abb3835717ce0)
-
-## 1. Add Citations from DOIs
-
-A digital object identifier (DOI) is a unique string that permanently identifies an article or document on the web.
-
-### 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)
-
-### 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
-
-
-## 2. Import Citations from BibTeX Files
-
-BibTeX files (`.bib`) are commonly used with LaTeX and can be exported from most reference managers like Zotero, Mendeley, or EndNote.
-
-### 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
-
-### 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
-
-[Watch video: Importing citations from BibTeX file](images/MshxlXndaLsk3WbJ0ZGy-RaR3QGIKD1ek3VXMAX31-v3.mp4)
-
-## 3. Insert Citations in Your Text
-
-Once citations are in your library, you can easily insert them:
-
-### 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
-
-### 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"**
-
-![Insert multiple citations](images/MshxlXndaLsk3WbJ0ZGy-V58UiaFTTyA5qx1tti7D-v1.png)
-
-## 4. Format and Arrange Citations
-
-### 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)
-
-### 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
-
-
-## 5. Update and Manage Citations
-
-### 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
-
-### Citation Keys
-- **Format**: `ref-citationkey` (lowercase)
-- **Example**: `Cockett2015-Elsevier` becomes `ref-cockett2015-elsevier`
-- **Use for**: Quick lookup with `[[cite:` command
-
-## Citation Examples
-
-| 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) |
-
-
-
-## Next Steps
-
-- [Add Figures, Images, and Media →](./figures-and-images.md)
-- [Create Internal References →](./internal-references.md)
-- [Export to PDF/LaTeX →](./export-latex.md)
-
----
-
-💡 **Tip:** Citations in Curvenote are clickable and will take you directly to the source article or document when clicked.
-
-⚡ **Important:
-Citation Management**
-
-- 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/export-pdf.md b/editor/export-pdf.md
deleted file mode 100644
index c799169..0000000
--- a/editor/export-pdf.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: PDF
-description: After creating an article in Curvenote, you can export and download your document as a PDF using a variety of professional templates!
----
-
-After creating an article in Curvenote, you can export and download your document as a PDF using a variety of professional templates!
-
-## 📺 Video Demo
-
-```{iframe} https://www.loom.com/embed/943fe51c06a74e6587f12cdec92934e0
-:label: P4FkCoWBJ0
-:align: center
-:width: 90%
-```
-
-## Exit Draft Mode
-
-Only a saved version of an article can be exported for download. If you are editing a **draft** you will need to exit **draft mode** (indicated in the footer👇) . Learn more `Drafts & Versions`
-
-```{figure} images/TnCP56I5qhrKLeVufPL4-d94DK2WzsIyus8Hqb4pq-v1.png
-:align: center
-:width: 100%
-```
-
-To export and download your article with the most recent changes made in **draft mode**\:
-
-```{figure} images/TnCP56I5qhrKLeVufPL4-XzFgTi9vwrgRY5S1SlIP-v1.png
-:align: center
-:width: 100%
-```
-
-- Click **SAVE VERSION** in the header👆
-  - This will create a new version of your article
-
-To export and download the most recently **saved** version of your article - any changes made in **draft mode** will not be included:
-
-- Click **STOP EDITING** in the header👆
-  - This will return you to a view of the last saved version of your article
-
-## Export and Download PDF
-
-```{tip}
-Only owners or collaborators can download articles.
-```
-
-You can now export and download your article! To do this:
-
-- Click the download {u}`⬇ `icon.
-- Click **Export As**.
-- Choose **PDF** format
-  - Click **Next**.
-- Select a **Template**.
-  - Hover over the thumbnail on the left for an expanded preview of the template layout.
-  - Click **Select**.
-- Complete the template specific instructions for Template Options.
-  - Each template has a variety of required and optional options to include such as author name, affiliation, email, etc. Learn more [Template Options](./export-template-options.md).
-  - Click **Next**.
-  - Other requirements such as abstracts and acknowledgements use tagged content. Learn more [Tagging Blocks](./export-tagging-blocks.md).
-- Click **EXPORT**.
-- Your article export is now processing.
-  - You can exit the window during processing. You will notified when your export is complete.
-- To **download** your PDF:
-  - In the original Exports pop-up:
-    - Click the ☁️⬇️ icon.
-  - If you have closed the pop-up:
-    - Click the download {u}`⬇ `icon**\:**.
-    - Select **Download PDF**.
-  - You can also download the log file for the PDF export.
-- Your exported article will be available for download by you or any of your collaborators until you save a new version.
-  - You will need to repeat this process for that version.
-
-```{figure} images/TnCP56I5qhrKLeVufPL4-LQG9wOZEfSBC3Zh63b5l-v1.mp4
-:name: k1GZtH4WgY
-:align: center
-:width: 70%
-```
-
-```{note}
-Don’t see the template you need? [Request a new template](mailto:support@curvenote.com?subject=Request%20for%20a%20latex%20template%20to%20be%20added%20to%20Curvenote) via email or [add a template](https://github.com/curvenote/templates) on Github!
-```
diff --git a/editor/figures-and-images.md b/editor/figures-and-images.md
deleted file mode 100644
index 387df5e..0000000
--- a/editor/figures-and-images.md
+++ /dev/null
@@ -1,137 +0,0 @@
----
-title: Add Figures, Images, and Media
-short_title: Add Figures & Images
----
-
-# 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 📺
-
-[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:
-
-### 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
-
-### Method 2: Copy and Paste
-- **Paste** images directly from your clipboard into a content block
-- Images will automatically upload and appear in your content
-
-### 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
-
-### 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
-
-![Add images using drag and drop](images/Z1isOjJQGvM22q5fhunb-N5l1Q6oYXvf6h3LU4dRz-v1.png)
-
-## 2. Create Standalone Image Blocks
-
-To display an image as its own block (separate from text):
-
-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
-
-## 3. Format Your Images
-
-Once uploaded, you'll see a formatting toolbar that allows you to:
-
-- **Adjust alignment** (left, center, right)
-- **Change width** (percentage of page width)
-- **Delete** the image if needed
-
-![Format images with toolbar](images/Z1isOjJQGvM22q5fhunb-Dp770ojYtbrTmXDe2Gy0-v1.png)
-
-## 4. Create Figures with Captions and Numbering
-
-Images and GIFs can be formatted as **Figures** with automatic numbering and captions:
-
-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**
-
-Figures are automatically numbered by their location on the page, starting at 1.
-
-![Create figures with captions](images/Z1isOjJQGvM22q5fhunb-sIdK5tPBxpH5QPoljim3-v1.png)
-
-## 5. Reference Figures in Your Text
-
-You can reference figures by their numbers using internal references:
-
-### Method 1: Command Menu
-- Type `/link to figure` in your text
-- Select the figure you want to reference from the dropdown menu
-
-### Method 2: Keyboard Shortcut
-- Type `[[fig:` in your text
-- Select the figure you want to reference from the dropdown menu
-
-When readers click on the reference, a preview of the image and its caption is displayed.
-
-## 6. Manage Image Versions
-
-Images are versioned independently in Curvenote. New versions are created when you:
-- Replace the image
-- Update the image caption
-
-### 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
-
-### 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"**
-
-![Manage image versions](images/Z1isOjJQGvM22q5fhunb-XSFXHCb26Y6uqqkIhsXz-v1.png)
-
-## 7. Update Image Settings
-
-You can access and update image settings including URL, title, description, caption, and tags:
-
-### 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"**
-
-### 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/myst.yml b/myst.yml
index bb94d90..0704109 100644
--- a/myst.yml
+++ b/myst.yml
@@ -40,6 +40,13 @@ project:
     - directives.mjs
   toc:
     - file: solutions.md
+    - title: Quick Start
+      children:
+        - file: quick-start/index.md
+        - file: quick-start/1-install.md
+        - file: quick-start/2-first-project.md
+        - file: quick-start/3-publish.md
+        - file: quick-start/4-examples.md
     - title: Getting Started
       children:
         - file: getting-started/what-is-curvenote.md
diff --git a/publishing/editorial-process.md b/publishing/editorial-process.md
deleted file mode 100644
index 0a1127e..0000000
--- a/publishing/editorial-process.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Editorial Process
----
-
-The editorial process we describe in this guide involves a single, centralized GitHub repository where all operations — submission, review, revision, and acceptance — are managed.
-This approach leverages the collaborative aspects of GitHub for peer-review and can offer full transparency of the editorial decisions, and represents a relatively simple editorial workflow. Below is a general overview of the editorial process, which can be tailored to specific venues and editorial teams.
-
-Submission
-: Authors submit their papers by forking the repository, creating a new branch and adding their manuscript or {term}`compendium` into a folder (e.g. `papers`). They the author opens a pull request (PR) to merge their branch into the main branch of the repository. The PR serves as the primary hub for discussion and review of the paper.
-
-Check and Preview
-: Upon submission, automated {term}`checks` are run via a GitHub Action. These verify that the {term}`submission` meets basic requirements such as adherence to templates and inclusion of necessary scholarly metadata such as author names, affiliations, abstracts, and inclusion of DOIs in references. A {term}`preview` of the work is created and accessible through a GitHub comment.
-
-Editorial Workflow
-: An editor is generally assigned to the submission after initial checks. This editor is responsible for overseeing the review process. They assess the paper's scope and topic to ensure it fits the publication's criteria and, if so, moves it forward in the review process.
-
-Reviewer Recruitment
-: The assigned editor recruits reviewers who are experts in the subject matter of the paper. These reviewers are tasked with evaluating the submission's quality, novelty, and accuracy. These reviewers are `@tagged` in the GitHub pull request, which facilitates all notifications and communication between the authors and the reviewers.
-
-Review Process
-: Reviewers access the {term}`preview` of the {term}`submission` and provide their feedback directly on the pull request through GitHub comments. This feedback can include both general comments and specific, inline suggestions for changes. The review process is transparent, with discussions visible publicly, which encourages thorough and constructive critiques.
-
-Author Revisions
-: Based on the feedback from reviewers, the author may make revisions to the submission. This often involves updating the pull request with new commits that reflect the changes suggested by the reviewers. The process of review and revision can cycle multiple times depending on the paper's initial quality and the extent of required revisions.
-
-Final Decision
-: Once the reviewers and the assigned editor(s) are satisfied with the revisions, the editor makes a decision on the paper. If accepted, the final version of the paper is merged into the main branch. The PR's merge signifies formal acceptance of the paper.
-
-Publication
-: After acceptance, the {term}`submission` is accessible in Curvenote and can be assigned a DOI and including the new publication on the journal's website or announcing through other channels.
-
-This workflow is inspired by the Journal of Open Source Software (JOSS) and SciPy Proceedings, and is designed foster a community-oriented approach where the _process_ is as open as the _content_.
diff --git a/quick-start/1-install.md b/quick-start/1-install.md
new file mode 100644
index 0000000..24145e8
--- /dev/null
+++ b/quick-start/1-install.md
@@ -0,0 +1,77 @@
+---
+title: Install Curvenote
+short_title: Install
+---
+
+# Install Curvenote
+
+## Quick Start
+Install the Curvenote CLI tool and authenticate with your account to start creating and publishing content
+
+The Curvenote CLI provides command-line access to all Curvenote features, allowing you to create projects, manage content, and publish sites directly from your terminal.
+
+## Before You Start
+
+Make sure you have:
+- Node.js v18 or later installed on your system
+- A terminal or command prompt accessible
+- A Curvenote account (optional for installation, required for publishing)
+- Administrator access if installing globally
+
+## 1. Install the CLI
+
+Open your terminal and run the installation command:
+
+```bash
+npm install -g curvenote
+```
+
+**What you'll see:**
+```
++ curvenote@1.2.3
+added 1 package in 2.3s
+```
+
+## 2. Verify Installation
+
+Confirm the CLI is properly installed:
+
+```bash
+curvenote --version
+```
+
+**What you'll see:**
+```
+1.2.3
+```
+
+## 3. Authenticate (Optional)
+
+Log in to your Curvenote account:
+
+```bash
+curvenote login
+```
+
+**What you'll see:**
+- Browser opens to Curvenote sign-in page
+- Sign in with your credentials
+- Return to terminal when complete
+- Confirmation message: `Logged in as your-username`
+
+## Next Steps
+
+- [Create Your First Project →](./2-first-project.md)
+- [Learn CLI Commands →](../cli/commands.md)
+- [Set Up Authentication →](../cli/authentication.md)
+
+---
+
+💡 **Tip:** The Curvenote CLI is open source and available on GitHub. You can contribute or report issues directly to the project.
+
+⚡ **Important: Troubleshooting**
+
+- **"command not found"**: Restart your terminal after installation
+- **Permission errors**: Use `sudo npm install -g curvenote` (macOS/Linux)
+- **Node.js required**: [Download Node.js](https://nodejs.org/) if not installed
+- **Version conflicts**: Update Node.js to v18 or later
diff --git a/quick-start/2-first-project.md b/quick-start/2-first-project.md
new file mode 100644
index 0000000..784cd16
--- /dev/null
+++ b/quick-start/2-first-project.md
@@ -0,0 +1,111 @@
+---
+title: Create Your First Project
+short_title: First Project
+---
+
+# Create Your First Project
+
+## Quick Start
+Create a new Curvenote project and start a local preview server to see your content live as you edit
+
+A Curvenote project contains your content files, site configuration, and assets. The local preview server provides instant feedback as you make changes to your content.
+
+## Before You Start
+
+Make sure you have:
+- Curvenote CLI installed and working
+- A terminal or command prompt open
+- A text editor ready for content creation
+- An idea for your project name
+
+## 1. Create a New Project
+
+Initialize a new Curvenote project with sample content:
+
+```bash
+curvenote init my-blog
+```
+
+**What you'll see:**
+```
+✨ Creating new Curvenote project: my-blog
+📁 Created project structure
+📝 Added sample content
+✅ Project ready!
+```
+
+## 2. Navigate to Your Project
+
+Change into your new project directory:
+
+```bash
+cd my-blog
+```
+
+## 3. Start Local Preview
+
+Launch the development server to preview your site:
+
+```bash
+curvenote start
+```
+
+**What you'll see:**
+```
+🚀 Starting local server...
+📖 Site available at: http://localhost:3000
+🔄 Live reload enabled
+```
+
+## 4. View Your Site
+
+Open your browser and navigate to the local URL:
+
+**Open:** http://localhost:3000
+
+**What you'll see:**
+- Your new site with sample content
+- Live preview that updates as you edit
+- Professional layout and styling
+
+## 5. Edit Your Content
+
+Open the main content file in your text editor:
+
+**File:** `content/index.md`
+
+**Try this example:**
+```markdown
+---
+title: My First Article
+---
+
+# Welcome to My Site!
+
+This is my first Curvenote article. 🎉
+
+## What I'm Working On
+
+- Research project A
+- Conference paper B
+- Lab documentation
+```
+
+**Save the file** → See changes instantly in your browser!
+
+## Next Steps
+
+- [Publish Your Site →](./3-publish.md)
+- [Add Figures and Media →](../authoring/add-figures-media.md)
+- [Customize Your Site →](../site-design/layout-and-theme.md)
+
+---
+
+💡 **Tip:** The local preview server automatically reloads when you save changes, so you can see your updates immediately without manual refresh.
+
+⚡ **Important: Project Structure**
+
+- **Add images**: Drop files in `images/` folder
+- **More pages**: Create new `.md` files in `content/`
+- **Customize**: Edit `curvenote.yml` for site settings
+- **Assets**: Use `public/` folder for static files
diff --git a/quick-start/3-publish.md b/quick-start/3-publish.md
new file mode 100644
index 0000000..4483a1b
--- /dev/null
+++ b/quick-start/3-publish.md
@@ -0,0 +1,85 @@
+---
+title: Publish Your Site
+short_title: Publish
+---
+
+# Publish Your Site
+
+## Quick Start
+Deploy your Curvenote project to the web with a single command to make your content accessible to anyone
+
+Publishing creates a live website from your local project, making your content available on the internet with a professional URL and optimized hosting.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content ready to publish
+- Curvenote CLI installed and authenticated
+- Content you want to share publicly
+- A stable internet connection
+
+## 1. Publish to Web
+
+Deploy your site with a single command:
+
+```bash
+curvenote publish
+```
+
+**What you'll see:**
+```
+🚀 Publishing your site...
+📝 Processing content...
+🌐 Deploying to web...
+✅ Published! Visit: https://your-site.curve.space
+```
+
+## 2. View Your Live Site
+
+Open the provided URL in your browser:
+
+**Visit:** https://your-site.curve.space
+
+**What you'll see:**
+- Your published site accessible to anyone
+- Professional web address
+- Fast, optimized hosting
+
+## 3. Update Your Site
+
+Make changes to your content, then republish:
+
+```bash
+curvenote publish
+```
+
+**What you'll see:**
+```
+🔄 Updating published site...
+✅ Updated! Changes live now
+```
+
+## 4. Set Up Custom Domain (Optional)
+
+Configure your own domain name:
+
+1. **Add CNAME record** pointing to `ssh.curve.space`
+2. **Email:** support@curvenote.com with your domain
+3. **Wait for confirmation** (usually 24 hours)
+
+## Next Steps
+
+- [Explore Examples →](./4-examples.md)
+- [Customize Your Site →](../site-design/layout-and-theme.md)
+- [Set Up Custom Domains →](../site-design/custom-domains.md)
+
+---
+
+💡 **Tip:** Always preview your site locally with `curvenote start` before publishing to ensure everything looks correct.
+
+⚡ **Important: Publishing Best Practices**
+
+- **Preview locally** before publishing to catch any issues
+- **Check your site** after publishing to ensure everything displays correctly
+- **Share your URL** with collaborators and readers
+- **Updates are instant** - no waiting for builds or deployments
diff --git a/quick-start/4-examples.md b/quick-start/4-examples.md
new file mode 100644
index 0000000..54acd29
--- /dev/null
+++ b/quick-start/4-examples.md
@@ -0,0 +1,160 @@
+---
+title: Common Examples
+short_title: Examples
+---
+
+# Common Examples
+
+## Quick Start
+Copy-paste solutions for adding figures, citations, code blocks, and interactive elements to your Curvenote content
+
+These examples show common patterns for enhancing your content with visual elements, references, and interactive components that make your research more engaging and reproducible.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote project with content files
+- Images or figures ready to add
+- References in BibTeX format
+- Code examples to include
+
+## 1. Add a Figure
+
+Include images and figures in your content:
+
+**File:** `content/my-article.md`
+
+```markdown
+---
+title: My Research Paper
+---
+
+# Introduction
+
+Here's my key finding:
+
+```{figure} images/results.png
+:alt: Experimental results showing significant improvement
+:width: 60%
+:align: center
+```
+
+The data shows a 40% improvement in performance.
+```
+
+## 2. Add Citations
+
+Include academic references in your work:
+
+**Add to your article:**
+```markdown
+## Literature Review
+
+Previous work by @smith2023 showed similar patterns.
+
+## References
+
+```{bibliography}
+:style: apa
+```
+```
+
+**Create:** `references.bib`
+```bibtex
+@article{smith2023,
+  title={Recent advances in the field},
+  author={Smith, J. and Jones, A.},
+  journal={Nature},
+  year={2023}
+}
+```
+
+## 3. Add Code Blocks
+
+Include executable code in your content:
+
+**In your article:**
+```markdown
+## Methods
+
+Here's the analysis code:
+
+```{code-cell} python
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Load data
+data = pd.read_csv('experiment.csv')
+
+# Create plot
+plt.figure(figsize=(10, 6))
+plt.plot(data['time'], data['value'])
+plt.title('Experimental Results')
+plt.show()
+```
+```
+
+## 4. Add Interactive Elements
+
+Create interactive visualizations:
+
+**Create interactive figure:**
+```markdown
+## Interactive Results
+
+```{code-cell} python
+import plotly.express as px
+
+fig = px.scatter(data, x='x', y='y', color='category')
+fig.show()
+```
+```
+
+## 5. Add Tables
+
+Include structured data in your content:
+
+**Simple table:**
+```markdown
+| Experiment | Result | Confidence |
+|------------|--------|------------|
+| Trial 1    | 85%    | ±2%        |
+| Trial 2    | 87%    | ±1%        |
+| Trial 3    | 86%    | ±3%        |
+```
+
+## 6. Add Navigation
+
+Configure site navigation and actions:
+
+**Edit:** `curvenote.yml`
+```yaml
+site:
+  nav:
+    - title: Home
+      url: /
+    - title: Research
+      url: /research
+    - title: Publications
+      url: /papers
+  actions:
+    - title: Contact
+      url: mailto:you@example.com
+```
+
+## Next Steps
+
+- [Learn More MyST Markdown →](../authoring/writing-markdown-myst-jupyter.md)
+- [Add Interactive Figures →](../authoring/interactive-figures.md)
+- [Organize Your Content →](../authoring/organize-content.md)
+
+---
+
+💡 **Tip:** Start with simple examples and gradually add more complex elements as you become comfortable with the syntax.
+
+⚡ **Important: Content Guidelines**
+
+- **Images**: Use `.png`, `.jpg`, or `.svg` formats for best compatibility
+- **Code**: Supports Python, R, Julia, and many other languages
+- **Math**: Use `$equation$` for inline math, `$$equation$$` for block equations
+- **Links**: `[text](url)` for external links, `[text](page.md)` for internal pages
diff --git a/quick-start/index.md b/quick-start/index.md
new file mode 100644
index 0000000..bbd7cdb
--- /dev/null
+++ b/quick-start/index.md
@@ -0,0 +1,98 @@
+---
+title: Quick Start Guide
+short_title: Quick Start
+---
+
+# Quick Start Guide
+
+## Quick Start
+Get from zero to published site in minutes with step-by-step instructions
+
+This guide provides everything you need to install Curvenote, create your first project, publish it to the web, and add common content elements like figures, citations, and code.
+
+## Before You Start
+
+Make sure you have:
+- Node.js v18 or later installed
+- A terminal or command prompt
+- A text editor for content creation
+- An internet connection for publishing
+
+## 1. Install Curvenote
+
+Install the CLI tool and authenticate with your account:
+
+**Command:**
+```bash
+npm install -g curvenote
+```
+
+**Time:** 30 seconds
+
+[Install Curvenote →](./1-install.md)
+
+## 2. Create Your First Project
+
+Set up a project and start a local preview server:
+
+**Commands:**
+```bash
+curvenote init my-site
+curvenote start
+```
+
+**Time:** 2 minutes
+
+[Create Your First Project →](./2-first-project.md)
+
+## 3. Publish Your Site
+
+Deploy your site to the web with a single command:
+
+**Command:**
+```bash
+curvenote publish
+```
+
+**Time:** 1 minute
+
+[Publish Your Site →](./3-publish.md)
+
+## 4. Explore Examples
+
+Add figures, citations, code blocks, and interactive elements:
+
+**Time:** 5 minutes
+
+[Explore Examples →](./4-examples.md)
+
+## What You'll Build
+
+- **Professional website** with your content
+- **Live preview** that updates as you edit
+- **Published site** accessible to anyone
+- **Interactive elements** like code and figures
+
+## Success Checklist
+
+- [ ] Curvenote installed and working
+- [ ] Local preview running at localhost:3000
+- [ ] Site published and accessible online
+- [ ] Content edited and updated
+
+## Next Steps
+
+- [Getting Started Guide →](../Getting Started/)
+- [Site Design & Customization →](../site-design/)
+- [Authoring Content →](../authoring/)
+
+---
+
+💡 **Tip:** Start with the basics, then explore advanced features as you need them. You can always come back to add more complexity later!
+
+⚡ **Important: Getting Help**
+
+- **Stuck?** Check the troubleshooting tips in each guide
+- **More details?** [Full documentation →](../Getting Started/)
+- **Community?** [Discourse forum →](https://discourse.curvenote.com)
+- **Support?** [Email us →](mailto:support@curvenote.com)
diff --git a/site-design/custom-domains.md b/site-design/custom-domains.md
new file mode 100644
index 0000000..2de1c7b
--- /dev/null
+++ b/site-design/custom-domains.md
@@ -0,0 +1,124 @@
+---
+title: Set Up Custom Domains
+short_title: Custom Domains
+description: Configure your own domain name for your Curvenote site
+---
+
+# Set Up Custom Domains
+
+## Quick Start
+Configure your own domain name to host your Curvenote site instead of using the default curve.space subdomain
+
+You can use Curvenote to host any custom domain that you own, for example a personal blog, lab website, or journal. Custom domains are available with the Curvenote Pro plan or require a subscription to a Lab Group site or Journal hosted with Curvenote.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote Pro plan or Lab Group/Journal subscription
+- A domain name you own and control
+- Access to your domain's DNS configuration
+- Your Curvenote site already set up and working
+
+## 1. Configure DNS Records
+
+Set up the DNS configuration for your custom domain:
+
+### Add CNAME Record
+Navigate to your domain's DNS configuration and add the following `CNAME` record:
+
+| Host name | Type | TTL | Data |
+|-----------|------|-----|------|
+| subdomain.example.com | CNAME | 1 hour | ssh.curve.space |
+
+**Example**: If your domain is `mylab.com` and you want to use `research.mylab.com`, add a CNAME record pointing `research.mylab.com` to `ssh.curve.space`.
+
+```{note}
+If you visit https://ssh.curve.space you will see a custom landing page that points back to this documentation - this is not what will be shown on your site!
+```
+
+## 2. Contact Curvenote Support
+
+Once your DNS is configured, contact Curvenote support to complete the setup:
+
+1. **Email** [support@curvenote.com](mailto:support@curvenote.com)
+2. **Include the following information**:
+   - Domain name (e.g., `research.mylab.com`)
+   - Curvenote username or team name that owns this domain
+   - Your journal name, if applicable
+
+Support will configure the domain on Curvenote's side and notify you when it's ready.
+
+## 3. Update Your Site Configuration
+
+Add your custom domain to your site configuration:
+
+### Edit Your Site Config
+Add the domain to your `curvenote.yml` or `myst.yml` file under the `domains:` list:
+
+```yaml
+site:
+  domains:
+    - your.curve.space
+    - research.mylab.com
+```
+
+You can keep the original curve.space domain alongside your custom domain.
+
+### Deploy Your Site
+Run the deployment command to apply the changes:
+
+```bash
+curvenote deploy
+```
+
+You'll see the domains you're deploying to in the output. Verify that your site is now accessible at your custom domain.
+
+## 4. Verify Your Setup
+
+After deployment, check that:
+
+1. **Your custom domain** loads your Curvenote site
+2. **The original curve.space domain** still works (if you kept it)
+3. **All content and functionality** works as expected
+4. **SSL certificate** is properly configured (automatic)
+
+## Naked Domains
+
+For "naked domains" (e.g., `mylab.com` without a subdomain):
+
+### Option 1: Contact Support
+Contact Curvenote support to configure naked domain support.
+
+### Option 2: Redirect Setup
+1. **Set up a redirect** from your naked domain to a `www` subdomain
+2. **Configure the `www` subdomain** using the CNAME method above
+3. **Point `www.mylab.com`** to `ssh.curve.space`
+
+## Troubleshooting
+
+### Common Issues
+- **DNS propagation delay**: Changes can take up to 24 hours to propagate
+- **Incorrect CNAME record**: Double-check the hostname and target
+- **Support not contacted**: Custom domains require Curvenote configuration
+- **Deployment fails**: Ensure the domain is configured by Curvenote first
+
+### Check DNS Propagation
+Use online tools like [whatsmydns.net](https://whatsmydns.net) to check if your DNS changes have propagated globally.
+
+## Next Steps
+
+- [Plan Your Site Design →](./planning.md)
+- [Set Up Site Navigation →](./navigation.md)
+- [Choose Layout & Theme →](./layout-and-theme.md)
+
+---
+
+💡 **Tip:** Custom domains are automatically configured with SSL certificates, so your site will be accessible via HTTPS without additional setup.
+
+⚡ **Important:
+Domain Configuration**
+
+- DNS changes can take up to 24 hours to propagate
+- Always contact Curvenote support before attempting to use a custom domain
+- Keep your original curve.space domain as a backup during setup
+- Test your site thoroughly after domain configuration
diff --git a/site-design/layout-and-theme.md b/site-design/layout-and-theme.md
new file mode 100644
index 0000000..43bfe54
--- /dev/null
+++ b/site-design/layout-and-theme.md
@@ -0,0 +1,146 @@
+---
+title: Choose a Layout & Theme
+short_title: Layout & Theme
+---
+
+# Choose a Layout & Theme
+
+## Quick Start
+Customize your site's visual appearance by selecting layouts, colors, fonts, and branding elements to match your organization's identity
+
+Your site's layout and theme determine how your content is presented to visitors. Curvenote provides flexible options to create a professional, branded appearance that enhances readability and user experience.
+
+## Before You Start
+
+Make sure you have:
+- A Curvenote account with access to your site's settings
+- Primary and secondary brand colors (hex values)
+- Logo and dark mode logo (SVG or PNG format)
+- Any preferred fonts or typography guidelines
+- Your site already created and accessible
+
+## 1. Access Site Settings
+
+Navigate to your site's design configuration:
+
+1. **Open the Curvenote web admin interface**
+2. **Select your site** from the dashboard
+3. **Go to "Design" or "Theme Settings"**
+4. **You'll see options** for layout, colors, fonts, and branding
+
+## 2. Choose Your Layout
+
+Select how your content will be displayed:
+
+### Layout Options
+- **Grid – Centered**: Content arranged in a centered grid layout
+- **Grid – Left**: Content aligned to the left in a grid format
+- **Normal**: Standard content width with traditional flow
+
+### Choose Based On
+- **Content type**: Articles, journals, or lab websites
+- **Audience preferences**: Academic vs. general public
+- **Brand guidelines**: Formal vs. modern appearance
+
+You can change this layout later as your needs evolve.
+
+## 3. Configure Brand Colors
+
+Set your site's color scheme:
+
+### Primary Color
+- **Purpose**: Main brand color for headers, buttons, and accents
+- **Format**: Hex color code (e.g., #003366)
+- **Consider**: Accessibility and contrast with text
+
+### Secondary Color
+- **Purpose**: Supporting color for backgrounds and highlights
+- **Format**: Hex color code (e.g., #FFFFFF)
+- **Consider**: How it complements your primary color
+
+### Preview Changes
+- **Test readability** of text on colored backgrounds
+- **Check contrast ratios** for accessibility
+- **View in both light and dark modes**
+
+## 4. Upload Your Logos
+
+Add your organization's branding:
+
+### Brand Logo
+- **Location**: Appears in the site header
+- **Format**: SVG or PNG (recommended: square format)
+- **Style**: Simple, clean design without text for flexibility
+- **Size**: Typically 200x200px or larger
+
+### Dark Mode Logo
+- **Purpose**: Used when visitors switch to dark mode
+- **Format**: Same as brand logo
+- **Consider**: How it looks on dark backgrounds
+
+## 5. Select Typography
+
+Choose fonts for different content types:
+
+### Title/Brand Font
+- **Use**: Main headings and site title
+- **Style**: Bold or distinctive font
+- **Examples**: Roboto, Open Sans, or your brand font
+
+### Main Text Font
+- **Use**: Body text and general content
+- **Style**: Easy-to-read sans-serif or serif
+- **Examples**: Inter, Source Sans Pro, or Georgia
+
+### Technical/Monospace Font
+- **Use**: Code snippets and inline commands
+- **Style**: Fixed-width font for code readability
+- **Examples**: Fira Code, JetBrains Mono, or Consolas
+
+## 6. Preview and Save
+
+Test your design choices:
+
+1. **Save your changes** in the settings
+2. **Preview your site** in both light and dark modes
+3. **Check different pages** to ensure consistency
+4. **Test on different devices** if possible
+5. **Verify accessibility** of color combinations
+
+## Design Examples
+
+### Research Journal
+- **Layout**: Grid – Centered
+- **Primary Color**: Dark blue (#003366)
+- **Secondary Color**: White (#FFFFFF)
+- **Font**: Sans-serif for clean, professional appearance
+
+### Lab Website
+- **Layout**: Grid – Left
+- **Primary Color**: University brand color
+- **Secondary Color**: Light gray (#F5F5F5)
+- **Font**: Modern sans-serif for readability
+
+### Conference Site
+- **Layout**: Normal
+- **Primary Color**: Conference theme color
+- **Secondary Color**: Complementary accent
+- **Font**: Professional serif for academic tone
+
+## Next Steps
+
+- [Plan Your Site Design →](./planning.md)
+- [Set Up Custom Domains →](./custom-domains.md)
+- [Configure Site Navigation →](./navigation.md)
+
+---
+
+💡 **Tip:** Start with a simple, clean design and refine it over time. You can always update your theme as your brand evolves.
+
+⚡ **Important:
+Design Best Practices**
+
+- Ensure sufficient contrast between text and backgrounds
+- Use consistent spacing and typography throughout
+- Test your design on different screen sizes
+- Keep your logo simple and recognizable at small sizes
\ No newline at end of file
diff --git a/site-design/navigation.md b/site-design/navigation.md
new file mode 100644
index 0000000..3f8f4a2
--- /dev/null
+++ b/site-design/navigation.md
@@ -0,0 +1,250 @@
+---
+title: Set Up Site Navigation
+short_title: Navigation
+description: Configure navigation menus, action buttons, and site structure for your Curvenote website
+---
+
+# Set Up Site Navigation
+
+## Quick Start
+Configure your site's navigation menu, action buttons, and page structure to help visitors find content and take desired actions
+
+Your site's navigation determines how visitors move through your content and what actions they can take. A well-organized navigation structure improves user experience and helps achieve your site's goals.
+
+## Before You Start
+
+Make sure you have:
+- Access to your site's configuration files
+- A clear understanding of your site's content structure
+- Key pages and sections identified
+- Important actions or downloads you want to highlight
+- Your site already created and accessible
+
+## 1. Plan Your Navigation Structure
+
+Before configuring, plan your site's information architecture:
+
+### Main Navigation Items
+- **Home/Overview**: Introduction to your site
+- **Content Sections**: Articles, research, publications
+- **About Pages**: Team, organization, mission
+- **Contact/Support**: How to reach you
+- **Resources**: Downloads, tools, additional content
+
+### Action Items
+- **Primary actions**: Submit, register, contact
+- **Downloads**: PDFs, datasets, resources
+- **External links**: Social media, partner sites
+
+## 2. Configure Main Navigation
+
+Set up the primary navigation menu in your site configuration:
+
+### Basic Navigation Structure
+Add navigation items to your `curvenote.yml` or `myst.yml` file:
+
+```yaml
+version: 1
+site:
+  nav:
+    - title: Home
+      url: /
+    - title: Research
+      url: /research
+    - title: Publications
+      url: /publications
+    - title: Team
+      url: /team
+    - title: Contact
+      url: /contact
+```
+
+### Navigation Best Practices
+- **Keep it simple**: 5-7 main items maximum
+- **Use clear labels**: Visitors should understand each link
+- **Logical order**: Most important items first
+- **Consistent naming**: Match your page titles
+
+## 3. Create Nested Dropdown Menus
+
+Organize related content with dropdown navigation:
+
+### Dropdown Structure
+```yaml
+site:
+  nav:
+    - title: Research
+      children:
+        - title: Current Projects
+          url: /research/projects
+        - title: Publications
+          url: /research/publications
+        - title: Data
+          url: /research/data
+    - title: About
+      children:
+        - title: Our Mission
+          url: /about/mission
+        - title: Team Members
+          url: /about/team
+        - title: Contact Us
+          url: /about/contact
+```
+
+### Dropdown Guidelines
+- **Group related items**: Logical content organization
+- **Limit depth**: One level of nesting maximum
+- **Clear parent labels**: Indicate what's in the dropdown
+- **Consistent structure**: Similar items grouped together
+
+## 4. Add Action Buttons
+
+Highlight important actions in your navigation:
+
+### Action Button Configuration
+```yaml
+site:
+  actions:
+    - title: Submit Paper
+      url: /submit
+    - title: Download PDF
+      url: public/thesis.pdf
+      static: true
+    - title: Contact Us
+      url: mailto:contact@example.com
+```
+
+### Action Button Types
+- **Internal pages**: Submit forms, contact pages
+- **External links**: Social media, partner sites
+- **Email links**: Direct contact via email
+- **File downloads**: PDFs, datasets, resources
+
+### Action Button Best Practices
+- **Clear call-to-action**: "Submit", "Download", "Contact"
+- **Strategic placement**: Most important actions first
+- **Consistent styling**: Match your site's design
+- **Mobile-friendly**: Ensure buttons work on all devices
+
+## 5. Include Static Files
+
+Add downloadable content to your navigation:
+
+### Static File Setup
+1. **Place files** in the `public` folder of your site
+2. **Add to navigation** with `static: true` flag
+3. **Files deploy** automatically with your site
+
+### Example Configuration
+```yaml
+site:
+  actions:
+    - title: Download Thesis
+      url: public/my_thesis.pdf
+      static: true
+    - title: View Dataset
+      url: public/research_data.csv
+      static: true
+```
+
+### Static File Guidelines
+- **Use descriptive titles**: "Download Research Paper" not "PDF"
+- **Organize files**: Group related downloads together
+- **Check file sizes**: Large files may affect loading
+- **Update regularly**: Keep downloads current
+
+## 6. Test Your Navigation
+
+Validate your navigation structure:
+
+1. **Test all links** work correctly
+2. **Check dropdown menus** function properly
+3. **Verify mobile navigation** on different devices
+4. **Test static file downloads** open correctly
+5. **Review navigation flow** from a visitor's perspective
+6. **Gather feedback** from team members or users
+
+## Navigation Examples
+
+### Research Journal
+```yaml
+site:
+  nav:
+    - title: Home
+      url: /
+    - title: Articles
+      url: /articles
+    - title: Submit
+      url: /submit
+    - title: About
+      url: /about
+  actions:
+    - title: Submit Paper
+      url: /submit
+    - title: View Guidelines
+      url: public/author_guidelines.pdf
+      static: true
+```
+
+### Lab Website
+```yaml
+site:
+  nav:
+    - title: Home
+      url: /
+    - title: Research
+      children:
+        - title: Current Projects
+          url: /research/projects
+        - title: Publications
+          url: /research/publications
+    - title: Team
+      url: /team
+    - title: Contact
+      url: /contact
+  actions:
+    - title: Join Our Lab
+      url: /join
+    - title: Download Code
+      url: public/lab_tools.zip
+      static: true
+```
+
+### Conference Site
+```yaml
+site:
+  nav:
+    - title: Home
+      url: /
+    - title: Program
+      url: /program
+    - title: Registration
+      url: /register
+    - title: Venue
+      url: /venue
+  actions:
+    - title: Register Now
+      url: /register
+    - title: Download Schedule
+      url: public/conference_schedule.pdf
+      static: true
+```
+
+## Next Steps
+
+- [Plan Your Site Design →](../site-design/planning.md)
+- [Choose Layout & Theme →](../site-design/layout-and-theme.md)
+- [Set Up Custom Domains →](./custom-domains.md)
+
+---
+
+💡 **Tip:** Start with a simple navigation structure and expand as your content grows. You can always reorganize and add new sections later.
+
+⚡ **Important:
+Navigation Best Practices**
+
+- Keep navigation simple and intuitive
+- Use clear, descriptive labels for all links
+- Test navigation on mobile devices
+- Ensure all links work and lead to relevant content
+- Consider user goals when organizing menu items
diff --git a/site-design/planning.md b/site-design/planning.md
new file mode 100644
index 0000000..8ae56aa
--- /dev/null
+++ b/site-design/planning.md
@@ -0,0 +1,166 @@
+---
+title: Plan Your Site Design
+short_title: Site Planning
+---
+
+# Plan Your Site Design
+
+## Quick Start
+Plan and configure your site's hero section, background images, and overall design strategy to create a compelling first impression
+
+Your site's hero section is the first thing visitors see. A well-designed hero unit can significantly improve user engagement and site navigation.
+
+## Before You Start
+
+Make sure you have:
+- Access to your site in the Curvenote Web Admin interface
+- High-quality background images or brand colors ready
+- Your key message, tagline, and call-to-action content
+- A clear understanding of your site's purpose and audience
+- Your site already created and accessible
+
+## 1. Access Hero Unit Settings
+
+Navigate to your site's hero configuration:
+
+1. **Open the Curvenote Web Admin interface**
+2. **Select your site** from the dashboard
+3. **Go to "Design" → "Hero Unit"**
+4. **You'll see options** for background, text, and buttons
+
+## 2. Choose Your Background
+
+Select a visual foundation for your hero section:
+
+### Background Image
+- **Recommended size**: 1920px wide for optimal display
+- **Format**: JPG, PNG, or WebP for web optimization
+- **Style**: High contrast with text for readability
+- **Consider**: How it looks on different screen sizes
+
+### Background Color
+- **Alternative**: Solid color using HEX code
+- **Choose**: A color that complements your brand
+- **Ensure**: Sufficient contrast with text elements
+
+### Background Tips
+- **Don't overpower text** - ensure readability
+- **Test on mobile devices** - images scale differently
+- **Consider loading speed** - optimize image file sizes
+
+## 3. Configure Hero Text Content
+
+Create compelling messaging for your visitors:
+
+### Heading
+- **Purpose**: Main attention-grabbing statement
+- **Style**: Short, impactful, and memorable
+- **Length**: 3-8 words maximum
+- **Example**: "Advancing Scientific Discovery"
+
+### Kicker (Optional)
+- **Purpose**: Small text above the heading
+- **Use**: For context, category, or emphasis
+- **Style**: Subtle but informative
+- **Example**: "Research Journal"
+
+### Tagline
+- **Purpose**: Brief explanation of your mission
+- **Length**: One sentence maximum
+- **Style**: Clear and benefit-focused
+- **Example**: "Publishing cutting-edge research in computational science"
+
+### Description
+- **Purpose**: Detailed explanation of your site
+- **Length**: 1-3 sentences
+- **Content**: What visitors will find and why they should explore
+- **Example**: "Discover peer-reviewed articles, interactive visualizations, and reproducible research from leading scientists worldwide."
+
+## 4. Add Call-to-Action Buttons
+
+Guide visitors to take specific actions:
+
+### Button Configuration
+- **Maximum**: Two buttons per hero section
+- **Customization**: Label, link, and styling options
+- **Behavior**: Open in same tab or new window
+
+### Link Options
+- **Internal pages**: About, Contact, Articles
+- **External URLs**: Social media, partner sites
+- **Email addresses**: Contact forms or direct email
+- **Downloads**: PDFs, datasets, or resources
+
+### Button Best Practices
+- **Clear action words**: "Read Articles", "Submit Paper"
+- **Contrasting colors**: Stand out from background
+- **Logical flow**: Primary action first, secondary second
+
+## 5. Adjust Layout and Styling
+
+Fine-tune the visual presentation:
+
+### Text Alignment
+- **Left**: Traditional, formal appearance
+- **Center**: Modern, balanced layout
+- **Consider**: Your brand personality and content length
+
+### Styling Options
+- **Boxed**: Text in a contained area with background
+- **Full-width**: Text spans the entire hero width
+- **Test**: Both light and dark mode appearances
+
+### Responsive Design
+- **Mobile optimization**: Text scales appropriately
+- **Image cropping**: Background adapts to screen size
+- **Button placement**: Accessible on all devices
+
+## 6. Test and Refine
+
+Validate your hero section design:
+
+1. **Preview on different devices** (desktop, tablet, mobile)
+2. **Test in both light and dark modes**
+3. **Verify all button links work correctly**
+4. **Check text readability and contrast**
+5. **Load time testing** for background images
+6. **Gather feedback** from team members or users
+
+## Design Examples
+
+### Research Journal
+- **Background**: Abstract scientific visualization
+- **Heading**: "Open Science Journal"
+- **Tagline**: "Advancing reproducible research"
+- **Buttons**: "Browse Articles", "Submit Paper"
+
+### Lab Website
+- **Background**: Lab equipment or research photos
+- **Heading**: "Computational Biology Lab"
+- **Tagline**: "Exploring the frontiers of biological data science"
+- **Buttons**: "Our Research", "Join Our Team"
+
+### Conference Site
+- **Background**: Conference venue or theme graphics
+- **Heading**: "SciPy 2024"
+- **Tagline**: "The premier conference for scientific Python"
+- **Buttons**: "Register Now", "View Schedule"
+
+## Next Steps
+
+- [Choose Layout & Theme →](./layout-and-theme.md)
+- [Set Up Site Navigation →](./navigation.md)
+- [Configure Custom Domains →](./custom-domains.md)
+
+---
+
+💡 **Tip:** Start with a simple hero design and iterate based on user feedback. You can always update images, text, and buttons as your site evolves.
+
+⚡ **Important:
+Hero Design Best Practices**
+
+- Keep text concise and scannable
+- Ensure high contrast between text and background
+- Use web-optimized images for fast loading
+- Test all links and buttons regularly
+- Consider accessibility for all users
diff --git a/sites/custom-domains.md b/sites/custom-domains.md
deleted file mode 100644
index 9e72dc8..0000000
--- a/sites/custom-domains.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Custom domains
-description: You can use Curvenote to host any custom domain that you own, for example a personal blog, lab-website, or journal.
-subject: How To
-venue: MyST Websites
----
-
-You can use Curvenote to host any custom domain that you own, for example a personal blog, lab-website, or journal. Note that custom domains are a feature of the Curvenote Pro plan (see [plans](https://curvenote.com/pricing)) or require a subscription to a Lab Group site or Journal that is hosted with Curvenote.
-
-## Update DNS
-
-🛠️ Navigate to your domain’s DNS configuration, and add the following `CNAME` record:
-
-```{list-table}
-:header-rows: 1
-:name: YoZ2KCweNO
-* - Host name
-  - Type
-  - TTL
-  - Data
-* - subdomain.example.com
-  - CNAME
-  - 1 hour
-  - ssh.curve.space
-```
-
-:::{note}
-If you visit <https://ssh.curve.space> you will see a custom landing page that points back to this documentation, this is not what will be shown on your site!
-:::
-
-Once you have completed that step, send [support@curvenote.com](mailto:support@curvenote.com) an email with the domain and we will ensure it is setup on our side. This will be automated in the future! 🤖
-
-🛠️ Email [support@curvenote.com](mailto:support@curvenote.com) and include:
-
-- domain name (e.g. `subdomain.example.com`)
-- Curvenote username or team name that owns this domain (e.g. `rowanc1`)
-- Your journal name, if appropriate
-
-## Deploying a stand-alone site
-
-🛠️ Add this domain to your site configuration under the `domains:` list. You can also keep the original curve.space domains in there if you wish.
-
-```yaml
-site:
-  domains:
-    - your.curve.space
-    - subdomain.example.com
-```
-
-🛠️ Redeploy your site using `curvenote deploy`
-
-You will not be able to complete this step if the domain is not configured by us! Once successful, you will see the domain(s) that you are deploying to in the list, and check that your domain is now visible at your custom subdomain.
-
-## Naked Domains
-
-If you wish to support "naked domains" (e.g. `example.com`), please contact support. Alternatively, you can redirect your naked domain to a `www` subdomain and then point that to `ssh.curve.space` using the `CNAME` method above.
diff --git a/sites/navigation.md b/sites/navigation.md
deleted file mode 100644
index 7019318..0000000
--- a/sites/navigation.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: Navigation
-description: >-
-  Set the navigation and action links on your Curvenote website, including being
-  able to link to static content.
----
-
-You can customize various aspects of your Curvenote site including links in the navigation top bar that are visible throughout your site. For example, in @fig:navigation-links, we see the links of `Home`, `Overview`, `Latest Research`, how to `Submit`, and about the `Team`.
-
-:::{figure} images/navigation-links.png
-:name: fig:navigation-links
-:width: 100%
-Navigation for a Curvenote [landing page](./landing-pages.md), which is defined for the entire site. Showing an example from [Elemental Microscopy](https://www.elementalmicroscopy.com/).
-:::
-
-## Navigation
-
-The `site.nav` can include any number of links to pages in your site. The `title` will be shown in the navigation bar, and the `url` is where you will navigate when you click! Please make sure this matches a URL that is accessible on your site.
-
-```yaml
-version: 1
-site:
-  nav:
-    - title: My PhD Thesis
-      url: /phd
-    - title: Nested Menu
-      children:
-        - title: My Menu Item
-          url: /a-link
-```
-
-The `nav` is a list of these links, and it can also create nested drop-downs by providing a `children` list for top level navigations. If `children` are provided, the `url` field will not be used as the click will open the drop-down.
-
-```{figure #fig-navigation} images/navigation.png
-:align: center
-:width: 90%
-
-An example of nested drop-down navigation on the <https://colab.stanford.edu> lab group site.
-```
-
-## Including Static Files
-
-You can include static files like PDF documents in the `public` folder in the root of your site; these will be deployed with the rest of your site. To include these in the action, put a `static: true`, which will ensure the PDF opens in a new tab and the URL is modified correctly. The `url` should point to your public folder.
-
-```yaml
-site:
-  actions:
-    - title: Download Thesis
-      url: public/my_thesis.pdf
-      static: true
-```
-
-For auto-generated PDF files from your content, you can build these with Curvenote.
-
-## Footer
-
-TODO: https://github.com/myst-ext/myst-ext-curvenote-web