Reorganize and update Getting Started documentation

.gitignore

@@ -5,3 +5,4 @@ content/jupyter/images
 content/overview/images
 content/export/images
 content/web/images
+.DS_Store

authoring/jupyter-notebooks.md

@@ -1,8 +1,161 @@
 ---
-title: Writing a Scientific Paper using Jupyter
+title: Write a Scientific Paper using Jupyter
 short_title: Write using Jupyter
 ---
 
-:::{important} More Coming Soon! 🚧
-We are actively working on the documentation. Please check back soon or send us an email asking about this page: [support@curvenote.com](mailto:support@curvenote.com)
-:::
+# Write a Scientific Paper using Jupyter
+
+## Quick Start
+Create scientific papers directly from Jupyter notebooks with integrated code, outputs, and narrative text
+
+Jupyter notebooks provide a powerful way to write scientific papers that combine code, analysis, visualizations, and narrative text in a single document. Curvenote enhances this workflow by adding version control, collaboration, and publishing capabilities.
+
+## Before You Start
+
+Make sure you have:
+- Jupyter Lab or Jupyter Notebook installed
+- A Curvenote project set up
+- Your research data and analysis ready
+- A clear structure for your paper
+
+## 1. Set Up Your Jupyter Environment
+
+Start with a well-organized Jupyter notebook:
+
+1. **Create a new notebook** in Jupyter Lab or Jupyter Notebook
+2. **Organize your notebook** with clear sections:
+   - Introduction and background
+   - Methods and data
+   - Analysis and results
+   - Discussion and conclusions
+3. **Use markdown cells** for narrative text between code cells
+4. **Execute all cells** to ensure outputs are generated
+
+## 2. Structure Your Paper
+
+Organize your notebook to follow scientific paper conventions:
+
+### Introduction Section
+- **Background and context** in markdown cells
+- **Literature review** with citations
+- **Research questions** and objectives
+- **Hypotheses** to be tested
+
+### Methods Section
+- **Data collection** procedures
+- **Code for data preprocessing**
+- **Analysis methods** with clear comments
+- **Statistical approaches** used
+
+### Results Section
+- **Code for analysis** with outputs
+- **Figures and visualizations**
+- **Statistical results** and tables
+- **Key findings** in markdown
+
+### Discussion Section
+- **Interpretation** of results
+- **Comparison** with previous work
+- **Limitations** and future work
+- **Conclusions** and implications
+
+## 3. Add Rich Content
+
+Enhance your paper with various content types:
+
+### Code and Analysis
+```python
+# Example analysis code
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Load and process data
+data = pd.read_csv('experiment_data.csv')
+results = analyze_data(data)
+
+# Create visualization
+plt.figure(figsize=(10, 6))
+plt.plot(results['x'], results['y'])
+plt.title('Experimental Results')
+plt.show()
+```
+
+### Narrative Text
+Use markdown cells for:
+- **Explanations** of methods and results
+- **Citations** and references
+- **Context** and background information
+- **Discussion** of implications
+
+### Interactive Elements
+- **Interactive plots** (Plotly, Bokeh)
+- **Data tables** with sorting/filtering
+- **Embedded widgets** for exploration
+- **Dynamic visualizations**
+
+## 4. Link to Curvenote
+
+Connect your Jupyter notebook to Curvenote:
+
+1. **Upload your notebook** to your Curvenote project
+2. **Link to local file** for version control
+3. **Sync changes** automatically
+4. **Collaborate** with co-authors
+
+## 5. Format for Publication
+
+Prepare your notebook for publication:
+
+1. **Review all outputs** are properly displayed
+2. **Check markdown formatting** is correct
+3. **Verify citations** are properly formatted
+4. **Test interactive elements** work as expected
+5. **Export to various formats** (PDF, HTML, etc.)
+
+## 6. Collaborate and Review
+
+Work with co-authors effectively:
+
+1. **Share your project** with collaborators
+2. **Use comments** for feedback and discussion
+3. **Track changes** with version control
+4. **Review and revise** collaboratively
+5. **Finalize** for submission
+
+## Best Practices
+
+### Code Organization
+- **Clear variable names** and comments
+- **Modular functions** for reusability
+- **Error handling** for robustness
+- **Documentation** for complex algorithms
+
+### Writing Style
+- **Clear, concise language** in markdown cells
+- **Proper scientific tone** and terminology
+- **Logical flow** between sections
+- **Consistent formatting** throughout
+
+### Data Management
+- **Reproducible code** with fixed random seeds
+- **Data versioning** and backup
+- **Clear data sources** and citations
+- **Open data** when possible
+
+## Next Steps
+
+- [Add Interactive Outputs →](../editor/interactive-outputs.md)
+- [Link Data and Code →](../editor/add-and-link-notebooks.md)
+- [Publish & Share Your Article →](../getting-started/publish-article.md)
+
+---
+
+💡 **Tip:** Jupyter notebooks in Curvenote maintain full interactivity when published, allowing readers to explore your analysis, run code, and interact with visualizations directly in the browser.
+
+⚡ **Important:
+Reproducible Research Best Practices**
+
+- Always include all necessary code and data
+- Use version control for your notebooks
+- Document your environment and dependencies
+- Test that your notebook runs from start to finish

cli/authentication.md

@@ -1,89 +1,72 @@
 ---
 title: Authentication
+short_title: Authentication
 ---
 
-Most translation and export functionality is local and **does not** require you to be logged into Curvenote. Additionally, the API for any public content on Curvenote does not require you to be authenticated. However, if you want to sync content from your _private_ Curvenote projects to a local folder, modify any online projects, or deploy a website you will need to be authenticated.
+**Goal:**  
+Sign in to the Curvenote CLI using an API token so you can work with private projects, sync content, and publish.
 
-The Curvenote CLI works on an API token that can be generated from your personal settings on [curvenote.com](https://curvenote.com).
+## 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
 
-## Creating an API Token
+Most translation/export of **public content** does not require authentication.
 
-API Tokens allow you to access your Curvenote content programmatically.
+## 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.
 
-🛠️ You can create an API token by clicking [here](https://curvenote.com/profile?settings=true&tab=profile-api) if you are signed in or navigating to your **Personal Settings**, which are available under your avatar in the top right.
-
-```{figure} images/settings-api-token.png
-:name: FdFCmj6QcJ
-:align: center
-:width: 70%
-
-Access the API Token by navigating to your **Personal Settings** by clicking on your avatar in the top right.
+## 2. Store the Token Locally
+Run:
+```bash
+curvenote token set
 ```
+Paste the API token when prompted.
 
-🛠️ Click on the **Generate New Token**, and give you token a description that you can recognize lated if you need to revoke it. You will be shown a screen that allows you to copy the API token for the next step.
+## 3. Store the Token as an Environment Variable
 
-```{figure} images/settings-api-copy-token.png
-:name: rm1dO7qLHx
-:align: center
-:width: 70%
+Useful for CI/CD or servers:
 
-Ensure that you copy your token for the next step. You will not be able to access this token again.
+```bash
+export CURVENOTE_TOKEN="API_TOKEN"
 ```
+The environment variable takes priority over stored tokens.
 
-🛠️ Copy the API Token. You will not be able to see this token again, so be sure to copy it!
+## 4. Switch Accounts
 
-## Sign In to Curvenote using the CLI
+If you have multiple accounts:
 
-🛠️ Sign into the Curvenote CLI using the command:
-
-```python
-curvenote token set
+```bash
+curvenote token select
 ```
 
-You will be asked for an API Token which you copied from your API Access settings in Curvenote (see above). The command will store a local config file that has your API token to be used for future calls to the library.
-
-### Validate you are signed in
-
-🛠️ You can validate that you are signed in using the command:
-
-```shell
+## 5. Check Authentication Status
+```bash
 curvenote auth list
 ```
+Shows your current account or indicates if not authenticated.
 
-This will print your username and email or tell you that you are not authenticated.
-This command will also list any other accounts that you can login as.
-
-### Changing Profiles
-
-If you have multiple Curvenote accounts, for example, as a bot for a submission system, you can switch profiles using:
-
-```shell
-curvenote token select
+## 6. Sign Out
+```bash
+curvenote token delete
 ```
 
-This will bring up a prompt to select which account you should use for the Curvenote API.
-
-### Authenticating on a Server
-
-You can also override the config path by having a `CURVENOTE_TOKEN` in your environment, this is helpful when using the Curvenote CLI from a continuous integration system or on a server.
-
-```shell
-export CURVENOTE_TOKEN="API_TOKEN"
+Removes the stored token. If using an environment variable, unset it:
+```bash
+unset CURVENOTE_TOKEN
 ```
 
-:::{warning} `CURVENOTE_TOKEN` environment variable takes priority
-If the environment variable is present, it will have precedence over any token you have set previously.
-The CLI will notify you through a log message about which token is being used.
-:::
-
-Alternatively, you can use the `curvenote token set $ENV_VAR` to set the token programmatically; we recommend not to paste your token into the command line directly as that will create an entry in your terminal history.
-
-## Sign Out of Curvenote
-
-To sign out of the Curvenote CLI, you can call:
-
-```shell
-curvenote token delete
-```
+💡 **Tips:**
+- You only need to authenticate if working with private projects or publishing to a site.  
+- Store the API token in an environment variable (`CURVENOTE_TOKEN`) for CI/CD.  
+- Use `curvenote token select` to switch between accounts.  
 
-This will remove the local config file with the API token in it. Note, if you have signed into the CLI using the environment variable, you can unset that using `unset CURVENOTE_TOKEN`. To confirm that you are logged out you can run the command `curvenote auth list` as before, and it should inform you that you are not authenticated.
+## Related Guides
+- [Install & Authenticate CLI (Tutorial)](install-cli.md)  
+- [Push, Submit, and Publish Content](push-submit-publish.md)  
+- [Set Up a Site for Publishing](setup-site.md)  
+- [Continuous Integration with Curvenote CLI](ci-cli.md)

editor/add-and-link-notebooks.md

@@ -1,25 +1,76 @@
 ---
 title: Add & Link Notebooks
+short_title: Add & Link Notebooks
 ---
 
+# Add & Link Notebooks
+
+## Quick Start
+Upload Jupyter notebooks to your Curvenote project and link them to local files for version control and collaboration
+
 Notebooks can be created in Jupyter then uploaded to a Curvenote project via the web app. You should always add pre-executed, saved notebooks to Curvenote so that outputs appear and are available for use. Notebooks that already exist on Curvenote can also be imported and linked to a local `.ipynb` file.
 
-## Upload a Notebook - Curvenote
+## Before You Start
 
-You can upload a Jupyter notebook to a Curvenote **project**. To upload an existing notebook:
+Make sure you have:
+- A Curvenote project open
+- A Jupyter notebook (`.ipynb` file) ready to upload
+- The notebook is saved with executed outputs (if you want to display results)
 
-- In the project navigation panel
-  - Click the **Upload ☁️⬆️** icon
-- Click to browse or drag and drop an `.ipynb` file from your computer
-  - Click **DONE**
+## 1. Upload a Notebook to Curvenote
 
-```{danger}
-The upload process for notebooks on Curvenote should only be used if you do not intend to run the notebook! The local copy of your notebook will not be linked to Curvenote (it does not contain the necessary metadata for versioning). If you need to run this notebook you will have to manually link your local copy. Learn more [Add & Link Notebooks](./add-and-link-notebooks.md).
+To upload an existing Jupyter notebook to your project:
 
-```
+1. **Open your project** in the Curvenote web app
+2. **In the project navigation panel:**
+   - Click the **Upload ☁️⬆️** icon
+3. **Add your notebook:**
+   - Click to browse and select your `.ipynb` file
+   - Or drag and drop the file from your computer
+4. **Click "DONE"** to complete the upload
 
-```{figure} images/m59m7JQmWVyPjlASj9v3-UGpUYCC2QlQIhNSTYmEh-v1.mp4
+```{figure} images/m59m7JQmWVyPjlASj9h3-UGpUYCC2QlQIhNSTYmEh-v1.mp4
 :name: tdrOpSRldZ
 :align: center
 :width: 100%
 ```
+
+## 2. Link Local Notebooks (Recommended)
+
+For notebooks you plan to continue working on, it's better to link your local copy:
+
+1. **Upload the notebook** to Curvenote first (following steps above)
+2. **In your local project folder:**
+   - Place your `.ipynb` file in the appropriate directory
+   - The file should be in the same location relative to your project structure
+3. **Curvenote will automatically detect** the local file and link it
+4. **Future changes** to your local notebook will sync with Curvenote
+
+## 3. Use Notebooks in Your Articles
+
+Once uploaded, you can:
+
+- **Display notebook outputs** as figures in your articles
+- **Reference specific cells** from your notebooks
+- **Create interactive elements** that readers can explore
+- **Version control** your notebooks alongside your articles
+
+
+⚡ **Important:
+Upload vs. Link Workflow**
+
+- **Upload only**: Use this if you don't plan to run the notebook again
+- **Link local file**: Use this if you need to continue working on the notebook
+
+The upload process does not create a link to your local file, so you'll need to manually link it if you want to continue editing.
+
+
+## Next Steps
+
+- [Add Figures, Images, and Media →](./figures-and-images.md)
+- [Create Interactive Outputs →](./interactive-outputs.md)
+- [Work with Jupyter Notebooks →](../authoring/jupyter-notebooks.md)
+
+---
+
+💡 **Tip:** Always save your notebooks with executed outputs before uploading to Curvenote. This ensures that figures, charts, and other results are visible in your articles.