From 93fb97c1712e1fc2aa446c9dada4fc94fbff2a06 Mon Sep 17 00:00:00 2001 From: Jill Hale Date: Mon, 25 Aug 2025 20:36:26 -0600 Subject: [PATCH 1/2] Completed updating/creating remaning docs, documentation restructuring and content consolidation. - Reorganized myst.yml with intuitive folder structure (Authoring, Publishing, Command Line Tools, Computational, Site Design, Reference, Getting Started) - Removed 'Quick Start' and 'Curvenote Editor' sections from TOC - Moved files to logical locations and updated all cross-references - Created comprehensive integrations/github.md reference guide - Added Getting Started section with 3 new guides: * account-setup.md - Account creation and profile management * first-steps-after-installation.md - Post-installation setup * basic-content-creation.md - Content creation fundamentals - Created authoring/myst-markdown.md with MyST syntax guide - Added authoring/adding-content.md for content management - Moved GitHub-related files to publishing/ (github-actions.md, deploying-myst-from-github.md, submissions-using-github.md) - Moved computational files to Computational/ directory - Moved export files to publishing/ (export-latex.md, export-pdf.md) - Moved interactive files to Computational/ (interactive-outputs-in-jupyter.md, reproducible-figures.md) - Renamed authoring/authors.md to authoring/manage-authors.md - Updated all new files to use consistent 'Overview' section headers - Made computational guides more cohesive by combining tips and important notes - Fixed rendering issues in myst-markdown.md and adding-content.md - Updated all cross-references to point to new file locations - Ensured content accuracy by removing 'invented' features - Removed duplicate update-content.md file - Deleted old quick-start/ directory files - Consolidated scattered GitHub documentation into unified reference - Fixed broken links throughout documentation - Applied consistent structure (Overview, Before You Start, numbered sections, Next Steps) - Used :::{important} syntax for callouts - Ensured all content reflects existing Curvenote features only" --- Computational/about-computational-articles.md | 531 ++++++++ Computational/computational-best-practices.md | 493 ++++++++ Computational/computational-tiers.md | 701 +++++++++++ Computational/embed-notebooks.md | 391 ++++++ Computational/interactive-figures.md | 540 +++++++++ .../interactive-outputs-in-jupyter.md | 0 Computational/live-compute.md | 715 +++++++++++ .../reproducible-figures.md | 0 Getting Started/account-setup.md | 172 +++ Getting Started/basic-content-creation.md | 194 +++ .../first-steps-after-installation.md | 199 +++ adding-content.md | 289 ----- authoring/adding-content.md | 458 +++++++ authoring/jupyter-notebooks.md | 4 +- authoring/latex.md | 8 +- authoring/{authors.md => manage-authors.md} | 4 +- authoring/markdown-myst-jupyter.md | 6 +- authoring/myst-markdown.md | 152 +++ authoring/typst.md | 8 +- authoring/version-history.md | 2 +- computational-articles.md | 16 - computational-tiers.md | 56 - deploying-myst-from-github.md | 123 -- github-actions.md | 131 -- integrations/github.md | 290 +++++ live-compute.md | 71 -- myst.yml | 163 +-- publishing/deploying-myst-from-github.md | 212 ++++ {Publish => publishing}/editorial-process.md | 42 +- {editor => publishing}/export-latex.md | 0 {Publish => publishing}/export-pdf-typst.md | 2 +- {Publish => publishing}/export-pdf.md | 2 +- publishing/github-actions.md | 210 ++++ publishing/submissions-using-github.md | 148 +++ submissions-using-github.md | 50 - update-content.md | 1064 +++++++++++++++++ 36 files changed, 6562 insertions(+), 885 deletions(-) create mode 100644 Computational/about-computational-articles.md create mode 100644 Computational/computational-best-practices.md create mode 100644 Computational/computational-tiers.md create mode 100644 Computational/embed-notebooks.md create mode 100644 Computational/interactive-figures.md rename {editor => Computational}/interactive-outputs-in-jupyter.md (100%) create mode 100644 Computational/live-compute.md rename {editor => Computational}/reproducible-figures.md (100%) create mode 100644 Getting Started/account-setup.md create mode 100644 Getting Started/basic-content-creation.md create mode 100644 Getting Started/first-steps-after-installation.md delete mode 100644 adding-content.md create mode 100644 authoring/adding-content.md rename authoring/{authors.md => manage-authors.md} (98%) create mode 100644 authoring/myst-markdown.md delete mode 100644 computational-articles.md delete mode 100644 computational-tiers.md delete mode 100644 deploying-myst-from-github.md delete mode 100644 github-actions.md create mode 100644 integrations/github.md delete mode 100644 live-compute.md create mode 100644 publishing/deploying-myst-from-github.md rename {Publish => publishing}/editorial-process.md (62%) rename {editor => publishing}/export-latex.md (100%) rename {Publish => publishing}/export-pdf-typst.md (99%) rename {Publish => publishing}/export-pdf.md (99%) create mode 100644 publishing/github-actions.md create mode 100644 publishing/submissions-using-github.md delete mode 100644 submissions-using-github.md create mode 100644 update-content.md diff --git a/Computational/about-computational-articles.md b/Computational/about-computational-articles.md new file mode 100644 index 0000000..da76fdb --- /dev/null +++ b/Computational/about-computational-articles.md @@ -0,0 +1,531 @@ +--- +title: Computational Articles +short_title: Computational Articles +--- + +# Computational Articles + +## Overview +Create publication-quality computational articles that combine interactive figures, executable code, and rich narrative content for reproducible scientific research + +Computational articles represent the next generation of scientific publishing, where research papers include not just static figures and text, but interactive visualizations, executable code, and computational environments that readers can explore and reproduce. Curvenote provides the infrastructure to create these advanced publications that bridge the gap between traditional papers and computational notebooks. + +## Before You Start + +Make sure you have: +- A Curvenote project for your computational article +- Jupyter environment with required scientific libraries +- Research data and computational workflows ready +- Understanding of your target journal or publication venue +- Knowledge of reproducibility best practices +- Interactive visualization libraries installed (Plotly, Altair, Bokeh) + +## 1. Understand Computational Article Types + +Choose the right structure for your research: + +### Computational Articles +**Structured around a core manuscript with attached supporting materials** + +**Characteristics:** +- **Primary focus**: Strong narrative flow with integrated computational elements +- **Interactive figures**: In-context interactive visualizations that execute independently +- **Notebook integration**: Jupyter notebooks embedded within the main content +- **JupyterLab environment**: Readers can launch separate computational environment +- **Reusability**: Encourages further experimentation and code reuse + +**Best for:** +- Research papers with computational components +- Articles requiring interactive data exploration +- Publications where reproducibility is crucial +- Papers with complex visualizations + +**Example**: [pyUserCalc](https://agu.curve.space/articles/NN0002) + +### Computational Reports & Tutorials +**Structured like a "book" with comprehensive computational documentation** + +**Characteristics:** +- **Primary focus**: Comprehensive documentation and exploration +- **Notebook collection**: Multiple notebooks within broader narrative +- **JupyterLab integration**: Readers can launch computational instances +- **In-place execution**: Optional execution within the report +- **Educational emphasis**: Step-by-step computational workflows + +**Best for:** +- Tutorial and educational content +- Comprehensive research reports +- Methodological papers +- Software documentation + +**Example**: [Tilt-Corrected BF-STEM](https://www.elementalmicroscopy.com/articles/EM000002) + +## 2. Plan Your Article Structure + +Design your computational article for maximum impact: + +### Core Manuscript Structure +```{myst} +# Your Computational Article Title + +## Abstract + +Brief summary including computational approach and key findings. + +## Introduction + +Background, research objectives, and computational methodology overview. + +## Methods + +### Computational Environment +Description of software, libraries, and computational setup. + +### Data Processing +Step-by-step data preparation and preprocessing workflow. + +### Analysis Pipeline +Detailed computational analysis methods and algorithms. + +## Results + +### Interactive Visualizations +Key findings presented through interactive figures. + +### Statistical Analysis +Computational results with supporting evidence. + +## Discussion + +Interpretation of computational results and implications. + +## Code Availability + +Information about code repositories and computational environments. + +## References + +Academic citations and computational resource references. +``` + +### Supporting Materials Organization +``` +your-article/ +├── manuscript.md # Main article content +├── notebooks/ +│ ├── data_processing.ipynb # Data preparation workflow +│ ├── analysis.ipynb # Main analysis notebook +│ └── visualizations.ipynb # Interactive figure generation +├── data/ +│ ├── raw/ # Original data files +│ └── processed/ # Cleaned and processed data +├── src/ +│ ├── utils.py # Utility functions +│ └── analysis.py # Analysis functions +├── requirements.txt # Python dependencies +├── environment.yml # Conda environment +└── README.md # Project documentation +``` + +## 3. Set Up Your Computational Environment + +Create a reproducible computational environment: + +### Python Environment Setup +```yaml +# environment.yml +name: computational-article +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - pandas>=1.5.0 + - numpy>=1.21.0 + - matplotlib>=3.5.0 + - seaborn>=0.11.0 + - plotly>=5.0.0 + - altair>=4.2.0 + - jupyterlab>=3.5.0 + - scipy>=1.9.0 + - scikit-learn>=1.1.0 + - pip + - pip: + - jupyterlab-myst>=0.2.0 + - myst-nb>=0.17.0 +``` + +### Requirements File +```txt +# requirements.txt +pandas>=1.5.0 +numpy>=1.21.0 +matplotlib>=3.5.0 +seaborn>=0.11.0 +plotly>=5.0.0 +altair>=4.2.0 +scipy>=1.9.0 +scikit-learn>=1.1.0 +jupyterlab>=3.5.0 +jupyterlab-myst>=0.2.0 +myst-nb>=0.17.0 +``` + +### System Dependencies +```txt +# apt.txt (for BinderHub) +gcc +gfortran +libopenblas-dev +liblapack-dev +``` + +## 4. Create Interactive Visualizations + +Develop engaging interactive figures for your research: + +### Data Loading and Preparation +```python +import pandas as pd +import numpy as np +import plotly.express as px +import altair as alt + +# Load research data +data = pd.read_csv('data/processed/research_data.csv') + +# Data preprocessing +data['date'] = pd.to_datetime(data['date']) +data['category'] = data['category'].astype('category') + +print(f"Dataset shape: {data.shape}") +print(f"Date range: {data['date'].min()} to {data['date'].max()}") +print(f"Categories: {data['category'].unique()}") +``` + +### Interactive Scatter Plot +```python +# Create interactive scatter plot +fig = px.scatter(data, + x='x_variable', + y='y_variable', + color='category', + size='magnitude', + hover_data=['date', 'condition', 'notes'], + title='Interactive Research Results') + +fig.update_layout( + xaxis_title="Independent Variable", + yaxis_title="Dependent Variable", + font=dict(size=12), + hovermode='closest' +) + +fig.show() +``` + +### Statistical Visualization +```python +import altair as alt + +# Create statistical chart +chart = alt.Chart(data).mark_circle().encode( + x='x_variable:Q', + y='y_variable:Q', + color='category:N', + size='magnitude:Q', + tooltip=['x_variable', 'y_variable', 'category', 'condition'] +).interactive() + +chart = chart.properties( + title='Statistical Analysis Results', + width=600, + height=400 +) + +chart +``` + +### Time Series Analysis +```python +import plotly.graph_objects as go + +# Create time series plot +fig = go.Figure() + +for category in data['category'].unique(): + subset = data[data['category'] == category] + fig.add_trace(go.Scatter( + x=subset['date'], + y=subset['value'], + mode='lines+markers', + name=category, + hovertemplate='Date: %{x}
Value: %{y}
Category: ' + category + )) + +fig.update_layout( + title='Time Series Analysis by Category', + xaxis_title='Date', + yaxis_title='Value', + hovermode='x unified' +) + +fig.show() +``` + +## 5. Integrate Notebooks with Articles + +Seamlessly combine computational notebooks with narrative content: + +### Import Notebook Cells +```{myst} +## Data Analysis + +Our computational analysis began with data preprocessing: + +[Import code cell showing data loading and cleaning] + +The cleaned dataset contained {numref}`Table %s ` observations across multiple variables. +``` + +### Reference Interactive Outputs +```{myst} +## Results + +The interactive visualization below shows the key findings: + +[Import interactive plot from notebook] + +As shown in the plot, there is a clear relationship between variables X and Y. +Readers can zoom, pan, and hover over data points to explore the results. +``` + +### Cross-Reference Computational Elements +```{myst} +## Methods + +The computational workflow consisted of three main steps: + +1. **Data Preprocessing**: See {numref}`Figure %s ` for the data processing pipeline +2. **Statistical Analysis**: The analysis code is available in the attached notebook +3. **Visualization**: Interactive figures were generated using Plotly and Altair + +### Computational Environment + +All analyses were performed using Python 3.9 with the following key libraries: +- pandas 1.5.0 for data manipulation +- numpy 1.21.0 for numerical computations +- plotly 5.0.0 for interactive visualizations +- scipy 1.9.0 for statistical analysis +``` + +## 6. Configure Computational Features + +Set up Curvenote's computational capabilities: + +### Curvenote Configuration +```yaml +# curvenote.yml +version: 1 +project: + title: "Your Computational Article" + description: "Research with interactive figures and computational notebooks" + + # Enable computational features + jupyter: true + computational: true + + # Export formats + exports: + - format: meca + - format: pdf + - format: typst + + # Dependencies + requirements: + - requirements.txt + - environment.yml + + # Resources + resources: + - notebooks/*.ipynb + - data/processed/* + - src/**/* + + # Computational settings + computational: + binderhub: true + jupyter: true + environment: environment.yml +``` + +### BinderHub Integration +```yaml +# .binder/environment.yml +name: computational-article +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - pandas>=1.5.0 + - numpy>=1.21.0 + - matplotlib>=3.5.0 + - plotly>=5.0.0 + - altair>=4.2.0 + - jupyterlab>=3.5.0 + - pip + - pip: + - jupyterlab-myst>=0.2.0 +``` + +## 7. Ensure Reproducibility + +Implement best practices for computational reproducibility: + +### Version Control +```bash +# Initialize git repository +git init +git add . +git commit -m "Initial computational article setup" + +# Create .gitignore +echo "*.ipynb_checkpoints/" >> .gitignore +echo "__pycache__/" >> .gitignore +echo "*.pyc" >> .gitignore +echo "data/raw/" >> .gitignore +echo "results/" >> .gitignore +``` + +### Data Management +```python +# data_management.py +import os +import hashlib +import pandas as pd + +def create_data_manifest(data_dir): + """Create manifest of all data files with checksums.""" + manifest = {} + + for root, dirs, files in os.walk(data_dir): + for file in files: + if file.endswith(('.csv', '.json', '.parquet')): + filepath = os.path.join(root, file) + with open(filepath, 'rb') as f: + checksum = hashlib.md5(f.read()).hexdigest() + + manifest[filepath] = { + 'size': os.path.getsize(filepath), + 'checksum': checksum, + 'modified': os.path.getmtime(filepath) + } + + return manifest + +# Create manifest +manifest = create_data_manifest('data/') +pd.DataFrame(manifest).T.to_csv('data_manifest.csv') +``` + +### Random Seed Management +```python +# reproducibility.py +import numpy as np +import random + +def set_random_seeds(seed=42): + """Set random seeds for reproducibility.""" + np.random.seed(seed) + random.seed(seed) + + # For PyTorch (if used) + try: + import torch + torch.manual_seed(seed) + if torch.cuda.is_available(): + torch.cuda.manual_seed(seed) + except ImportError: + pass + + # For TensorFlow (if used) + try: + import tensorflow as tf + tf.random.set_seed(seed) + except ImportError: + pass + +# Use in your analysis +set_random_seeds(42) +``` + +## 8. Publish and Share + +Prepare your computational article for publication: + +### Pre-Publication Checklist +- [ ] All code cells execute without errors +- [ ] Interactive figures work correctly +- [ ] Computational environment is reproducible +- [ ] Data files are properly organized +- [ ] Dependencies are documented +- [ ] Random seeds are set for reproducibility +- [ ] Code is well-documented and commented +- [ ] README file explains how to reproduce results + +### Export Options +```bash +# Export to various formats +curvenote export --format pdf +curvenote export --format typst +curvenote export --format meca + +# Deploy to Curvenote site +curvenote deploy +``` + +### Share Computational Environment +```markdown +## Computational Environment + +This article was created using the following computational environment: + +- **Python**: 3.9.0 +- **Key Libraries**: pandas 1.5.0, numpy 1.21.0, plotly 5.0.0 +- **JupyterLab**: 3.5.0 +- **Operating System**: Ubuntu 20.04 + +### Reproducing Results + +1. Clone the repository: `git clone [repository-url]` +2. Install dependencies: `conda env create -f environment.yml` +3. Activate environment: `conda activate computational-article` +4. Launch JupyterLab: `jupyter lab` +5. Open and run notebooks in order + +### Interactive Features + +- **Launch JupyterLab**: Click the "Launch Jupyter" button to open a computational environment +- **Interactive Figures**: Hover, zoom, and pan on interactive visualizations +- **Code Execution**: Run code cells directly in the article +``` + +## Next Steps + +- [Learn about Computational Best Practices →](./best-practices.md) +- [Create Interactive Figures →](./interactive-figures.md) +- [Embed Notebooks in Computational Content →](./embed-notebooks.md) +- [Understand Live Compute →](../live-compute.md) +- [Explore Computational Tiers →](../computational-tiers.md) + +--- + +💡 **Tip:** Start with a clear narrative structure and gradually integrate computational elements. Always test your interactive features before publication. Follow these computational article best practices: + +- **Reproducibility first**: Ensure all results can be reproduced by readers +- **Interactive engagement**: Use interactive figures to enhance understanding +- **Clear documentation**: Provide comprehensive setup and usage instructions +- **Performance optimization**: Optimize interactive elements for web display +- **Version control**: Use git to track changes and enable collaboration +- **Testing**: Verify all computational elements work across platforms diff --git a/Computational/computational-best-practices.md b/Computational/computational-best-practices.md new file mode 100644 index 0000000..bea1eea --- /dev/null +++ b/Computational/computational-best-practices.md @@ -0,0 +1,493 @@ +--- +title: Computational Best Practices +short_title: Best Practices +--- + +# Computational Best Practices + +## Overview +Follow best practices for creating reproducible, maintainable, and scalable computational research with Curvenote + +Creating computational articles and reports requires careful attention to reproducibility, dependency management, and performance optimization. This guide provides comprehensive best practices for developing computational content that works reliably across different environments and scales effectively with your audience. + +## Before You Start + +Make sure you have: +- A Curvenote project with computational content +- Understanding of your target computational tier +- Access to version control (Git) +- Knowledge of your programming language ecosystem +- Clear documentation requirements + +## 1. Environment Management + +Set up reproducible computational environments: + +### Use REES-Compatible Configuration Files +Create standard dependency management files that work with BinderHub: + +**Python (`requirements.txt`):** +```txt +# Core scientific packages +pandas>=1.5.0 +numpy>=1.21.0 +matplotlib>=3.5.0 +seaborn>=0.11.0 + +# Interactive visualization +plotly>=5.0.0 +altair>=4.2.0 + +# Jupyter and MyST support +jupyterlab>=3.5.0 +jupyterlab-myst>=0.2.0 + +# Specific versions for reproducibility +scikit-learn==1.2.0 +scipy==1.9.0 +``` + +**Conda (`environment.yml`):** +```yaml +name: my-research +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - pandas>=1.5.0 + - numpy>=1.21.0 + - matplotlib>=3.5.0 + - jupyterlab>=3.5.0 + - pip + - pip: + - plotly>=5.0.0 + - altair>=4.2.0 + - jupyterlab-myst>=0.2.0 +``` + +**R (`install.R`):** +```r +# Install required R packages +install.packages(c( + "tidyverse", + "ggplot2", + "dplyr", + "knitr", + "rmarkdown" +)) + +# Install from Bioconductor if needed +if (!requireNamespace("BiocManager", quietly = TRUE)) + install.packages("BiocManager") +BiocManager::install(c("DESeq2", "edgeR")) +``` + +### System Dependencies +For packages requiring system libraries, use `apt.txt`: + +```txt +# System packages for scientific computing +gcc +gfortran +libblas-dev +liblapack-dev +libhdf5-dev +libnetcdf-dev +``` + +## 2. Reproducibility Standards + +Ensure your computational work can be reproduced by others: + +### Set Random Seeds +```python +import numpy as np +import random +import os + +# Set seeds for reproducibility +np.random.seed(42) +random.seed(42) + +# For TensorFlow/PyTorch +import tensorflow as tf +tf.random.set_seed(42) + +# For R +set.seed(42) +``` + +### Document Package Versions +```python +# Create a version tracking script +import pandas as pd +import numpy as np +import matplotlib.pyplot as plt +import seaborn as sns + +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__}") +``` + +### Version Control Best Practices +```bash +# Initialize git repository +git init + +# Create .gitignore for computational projects +echo "*.ipynb_checkpoints/" >> .gitignore +echo "__pycache__/" >> .gitignore +echo "*.pyc" >> .gitignore +echo ".ipynb_checkpoints/" >> .gitignore +echo "data/raw/" >> .gitignore +echo "results/" >> .gitignore + +# Commit environment files +git add requirements.txt environment.yml +git commit -m "Add reproducible environment configuration" +``` + +## 3. Data Management + +Handle data efficiently and reproducibly: + +### Data Organization +``` +project/ +├── data/ +│ ├── raw/ # Original, unprocessed data +│ ├── processed/ # Cleaned and processed data +│ └── external/ # External datasets +├── notebooks/ # Jupyter notebooks +├── src/ # Source code +├── results/ # Output files +└── docs/ # Documentation +``` + +### Data Loading Functions +```python +def load_data_safely(filepath, **kwargs): + """Load data with proper error handling and logging.""" + try: + if filepath.endswith('.csv'): + data = pd.read_csv(filepath, **kwargs) + elif filepath.endswith('.h5'): + data = pd.read_hdf(filepath, **kwargs) + else: + raise ValueError(f"Unsupported file format: {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 function +data = load_data_safely('data/processed/experiment_results.csv') +``` + +### Large Data Handling +For datasets larger than 50GB: + +```yaml +# In curvenote.yml +project: + resources: + # Use external repositories for large datasets + - url: https://doi.org/10.5281/zenodo.1234567 + file: data/external/large_dataset.h5 + - url: https://doi.org/10.5281/zenodo.7654321 + file: data/external/another_dataset.csv +``` + +## 4. Performance Optimization + +Optimize your computational content for different tiers: + +### Memory Management +```python +# Use generators for large datasets +def process_large_file(filepath, chunk_size=10000): + """Process large files in chunks to manage memory.""" + for chunk in pd.read_csv(filepath, chunksize=chunk_size): + # Process each chunk + processed_chunk = process_chunk(chunk) + yield processed_chunk + +# Use efficient data structures +import numpy as np + +# Use appropriate dtypes +data = pd.read_csv('large_file.csv', dtype={ + 'id': 'int32', + 'value': 'float32', + 'category': 'category' +}) +``` + +### Caching Results +```python +import joblib +from functools import lru_cache + +# Cache expensive computations +@lru_cache(maxsize=128) +def expensive_calculation(parameter): + """Cache results of expensive calculations.""" + # Your expensive computation here + return result + +# Use joblib for larger objects +def train_model(data, parameters): + """Train model with caching.""" + cache_file = f"model_cache_{hash(str(parameters))}.pkl" + + try: + model = joblib.load(cache_file) + print("Loaded model from cache") + except FileNotFoundError: + model = train_expensive_model(data, parameters) + joblib.dump(model, cache_file) + print("Trained and cached new model") + + return model +``` + +## 5. Interactive Content Design + +Create engaging and efficient interactive visualizations: + +### Choose Appropriate Libraries +```python +# For static, publication-quality plots +import matplotlib.pyplot as plt +import seaborn as sns + +# For interactive web plots +import plotly.express as px +import plotly.graph_objects as go + +# For declarative statistical plots +import altair as alt + +# For complex dashboards +import dash +from dash import dcc, html +``` + +### Optimize Interactive Plots +```python +# Use efficient plotting for large datasets +def create_efficient_plot(data, max_points=10000): + """Create efficient interactive plot for large datasets.""" + if len(data) > max_points: + # Sample data for plotting + plot_data = data.sample(n=max_points, random_state=42) + else: + plot_data = data + + fig = px.scatter(plot_data, x='x', y='y', + hover_data=['category', 'value'], + title='Interactive Plot (sampled for performance)') + + return fig + +# Use appropriate plot types +def choose_plot_type(data_size, data_type): + """Choose appropriate plot type based on data characteristics.""" + if data_size > 10000: + return 'histogram' # Efficient for large datasets + elif data_type == 'categorical': + return 'bar' # Good for categorical data + else: + return 'scatter' # Default for small datasets +``` + +## 6. Error Handling and Validation + +Implement robust error handling for computational content: + +### Input Validation +```python +def validate_input_data(data, required_columns, data_types): + """Validate input data before processing.""" + # Check required columns + missing_columns = set(required_columns) - set(data.columns) + if missing_columns: + raise ValueError(f"Missing required columns: {missing_columns}") + + # Check data types + for col, expected_type in data_types.items(): + if col in data.columns: + actual_type = str(data[col].dtype) + if expected_type not in actual_type: + raise TypeError(f"Column {col} has type {actual_type}, expected {expected_type}") + + # Check for missing values + missing_count = data[required_columns].isnull().sum() + if missing_count.any(): + print(f"Warning: Missing values found: {missing_count[missing_count > 0]}") + + return True +``` + +### Graceful Degradation +```python +def create_visualization(data, interactive=True): + """Create visualization with graceful degradation.""" + try: + if interactive and len(data) < 5000: + # Create interactive plot + fig = px.scatter(data, x='x', y='y') + return fig + else: + # Fall back to static plot + fig, ax = plt.subplots() + ax.scatter(data['x'], data['y']) + return fig + except Exception as e: + # Fall back to basic plot + print(f"Interactive plot failed: {e}") + fig, ax = plt.subplots() + ax.plot(data['x'], data['y']) + return fig +``` + +## 7. Testing and Validation + +Test your computational content thoroughly: + +### Unit Testing +```python +import unittest +import pandas as pd +import numpy as np + +class TestDataProcessing(unittest.TestCase): + def setUp(self): + """Set up test data.""" + self.test_data = pd.DataFrame({ + 'x': [1, 2, 3, 4, 5], + 'y': [2, 4, 6, 8, 10] + }) + + def test_data_loading(self): + """Test data loading function.""" + result = load_data_safely('test_data.csv') + self.assertIsNotNone(result) + self.assertEqual(len(result), 5) + + def test_calculation(self): + """Test mathematical calculations.""" + result = expensive_calculation(42) + self.assertIsNotNone(result) + self.assertGreater(result, 0) + +# Run tests +if __name__ == '__main__': + unittest.main() +``` + +### Integration Testing +```bash +# Test your environment on mybinder.org +# 1. Push your code to a public GitHub repository +# 2. Visit https://mybinder.org +# 3. Enter your repository URL +# 4. Test that your notebooks run correctly + +# Test MECA export locally +curvenote export meca +# Check the generated zip file contains all expected files +``` + +## 8. Documentation and Metadata + +Provide comprehensive documentation for your computational work: + +### Project Configuration +```yaml +# curvenote.yml +version: 1 +project: + title: "My Computational Research" + description: "Reproducible analysis of experimental data" + + # Enable computation + jupyter: true + + # Export formats + exports: + - format: meca + - format: pdf + - format: typst + + # Dependencies + requirements: + - requirements.txt + - environment.yml + - apt.txt + + # Resources + resources: + - data/processed/* + - models/*.pkl + - src/**/* + + # Computational settings + computational: + binderhub: true + jupyter: true +``` + +### README Documentation +```markdown +# Computational Research Project + +## Overview +Brief description of the research and computational approach. + +## Setup +1. Install dependencies: `pip install -r requirements.txt` +2. Download data: `python scripts/download_data.py` +3. Run analysis: `jupyter lab` + +## Reproducing Results +1. Follow the notebooks in order: `01_data_preprocessing.ipynb`, `02_analysis.ipynb` +2. All random seeds are set for reproducibility +3. Results are saved in `results/` directory + +## Data Sources +- Primary dataset: DOI 10.5281/zenodo.1234567 +- External validation: DOI 10.5281/zenodo.7654321 + +## Computational Requirements +- Python 3.9+ +- 8GB RAM recommended +- GPU optional (CUDA 11.0+) +``` + +## Next Steps + +- [Learn about Computational Articles →](../computational-articles.md) +- [Understand Live Compute →](../live-compute.md) +- [Explore Computational Tiers →](../computational-tiers.md) +- [Link Data and Code →](../authoring/link-data-code.md) + +--- + +💡 **Tip:** Start with a simple, reproducible environment and gradually add complexity as needed. Test your setup on mybinder.org before publishing. Follow these key principles: + +- **Reproducibility first**: Always set random seeds and document package versions +- **Environment management**: Use REES-compatible configuration files +- **Performance optimization**: Choose appropriate computational tiers and optimize for your audience +- **Error handling**: Implement robust error handling and graceful degradation +- **Testing**: Test your environment thoroughly before publishing +- **Documentation**: Provide clear setup and reproduction instructions diff --git a/Computational/computational-tiers.md b/Computational/computational-tiers.md new file mode 100644 index 0000000..98ce564 --- /dev/null +++ b/Computational/computational-tiers.md @@ -0,0 +1,701 @@ +--- +title: Computational Tiers +short_title: Computational Tiers +--- + +# Computational Tiers + +## Overview +Understand Curvenote's compute service tiers and choose the right level of computational resources for your interactive articles and research projects + +Curvenote provides a range of compute services delivered through a private BinderHub infrastructure, ensuring that all computational environments are isolated, secure, and optimized for performance. These tiers scale according to your needs, allowing you to select the appropriate level of compute resources based on expected traffic, interaction complexity, and computational requirements of your articles. + +## Before You Start + +Make sure you have: +- A Curvenote project with computational content +- Understanding of your expected user traffic and interaction patterns +- Knowledge of your computational requirements and complexity +- Budget considerations for compute resources +- Contact information for Curvenote consultation + +## 1. Understand Compute Service Architecture + +Learn how Curvenote's compute infrastructure works: + +### Private BinderHub Infrastructure +```yaml +# Computational Infrastructure Overview +compute_services: + infrastructure: "Private BinderHub" + isolation: "Per-journal/article resource isolation" + security: "Secure, managed computational environments" + storage: "Pre-stored images for fast access" + scaling: "On-demand resource allocation" +``` + +### Resource Allocation Model +```python +# Resource allocation example +class ComputeAllocation: + def __init__(self, tier_level): + self.tier = tier_level + self.concurrent_users = 0 + self.active_sessions = [] + self.resource_limits = self.get_tier_limits() + + def get_tier_limits(self): + limits = { + 'tier1': {'cpu': '2 cores', 'memory': '4GB', 'storage': '10GB'}, + 'tier2': {'cpu': '4 cores', 'memory': '8GB', 'storage': '20GB'}, + 'tier3': {'cpu': '8+ cores', 'memory': '16GB+', 'storage': '50GB+'} + } + return limits.get(self.tier, limits['tier1']) + + def check_availability(self): + """Check if resources are available for new user.""" + return len(self.active_sessions) < self.resource_limits['max_users'] +``` + +### On-Demand Activation +```mermaid +flowchart LR + A[Reader Opens Article] --> B{Interactive Content} + B -->|No| C[Static Reading] + B -->|Yes| D[Compute Request] + D --> E[Resource Check] + E --> F[Launch Environment] + F --> G[Interactive Session] + G --> H[45min Timeout] + H --> I[Resource Release] +``` + +## 2. Explore Compute Tier Options + +Choose from three main computational tiers: + +### Tier 1: Shared Compute +**Entry-level compute service for lab groups and small journals** + +**Characteristics:** +- **Infrastructure**: Shared end-user servers +- **Isolation**: Multi-tenant environment +- **Performance**: Suitable for lightweight interactions +- **Cost**: Most cost-effective option +- **Scaling**: Automatic resource sharing + +**Best for:** +- Lab groups and small research teams +- Independent journals with low traffic +- Lightweight interactive visualizations +- Educational content and tutorials +- Proof-of-concept projects + +**Resource Limits:** +```yaml +tier1_limits: + cpu: "2 cores per session" + memory: "4GB RAM per session" + storage: "10GB per session" + concurrent_users: "Up to 10 simultaneous sessions" + session_timeout: "45 minutes" + startup_time: "< 30 seconds" +``` + +### Tier 2: Dedicated Single Instance +**Dedicated compute host for individual journals or projects** + +**Characteristics:** +- **Infrastructure**: Dedicated single-instance host +- **Isolation**: Journal/project-specific environment +- **Performance**: Improved availability and consistency +- **Cost**: Mid-range pricing +- **Scaling**: Manual scaling based on needs + +**Best for:** +- Medium-sized journals and collections +- Research projects with moderate traffic +- Articles with complex interactive features +- Consistent performance requirements +- Growing computational needs + +**Resource Limits:** +```yaml +tier2_limits: + cpu: "4 cores per session" + memory: "8GB RAM per session" + storage: "20GB per session" + concurrent_users: "Up to 25 simultaneous sessions" + session_timeout: "45 minutes" + startup_time: "< 20 seconds" + availability: "99.5% uptime" +``` + +### Tier 3: Dedicated Cluster-Based Hub +**High-performance cluster for large-scale computational projects** + +**Characteristics:** +- **Infrastructure**: Dedicated cluster-based hub +- **Isolation**: Complete resource isolation +- **Performance**: Maximum availability and reliability +- **Cost**: Premium pricing, cost-effective at scale +- **Scaling**: Automatic cluster scaling + +**Best for:** +- Large journals and major publications +- High-traffic computational articles +- Complex data analysis workflows +- Real-time computational requirements +- Enterprise-level projects + +**Resource Limits:** +```yaml +tier3_limits: + cpu: "8+ cores per session" + memory: "16GB+ RAM per session" + storage: "50GB+ per session" + concurrent_users: "50+ simultaneous sessions" + session_timeout: "45 minutes" + startup_time: "< 15 seconds" + availability: "99.9% uptime" + auto_scaling: true +``` + +## 3. Assess Your Computational Needs + +Evaluate your requirements to choose the right tier: + +### Traffic Analysis +```python +# Traffic assessment tool +def assess_traffic_needs(monthly_readers, interaction_rate, peak_multiplier): + """ + Assess computational traffic needs. + + Args: + monthly_readers: Average monthly unique readers + interaction_rate: Percentage who use interactive features (0-1) + peak_multiplier: Peak traffic multiplier (e.g., 3x for conferences) + + Returns: + dict: Traffic assessment results + """ + daily_readers = monthly_readers / 30 + daily_interactions = daily_readers * interaction_rate + peak_daily_interactions = daily_interactions * peak_multiplier + + # Estimate concurrent users (assuming 45-minute sessions) + concurrent_users = peak_daily_interactions * 0.1 # 10% concurrent + + return { + 'daily_interactions': daily_interactions, + 'peak_daily_interactions': peak_daily_interactions, + 'estimated_concurrent_users': concurrent_users, + 'recommended_tier': get_recommended_tier(concurrent_users) + } + +def get_recommended_tier(concurrent_users): + """Get tier recommendation based on concurrent users.""" + if concurrent_users <= 10: + return "Tier 1: Shared Compute" + elif concurrent_users <= 25: + return "Tier 2: Dedicated Single Instance" + else: + return "Tier 3: Dedicated Cluster-Based Hub" +``` + +### Computational Complexity Assessment +```python +# Complexity assessment +def assess_computational_complexity(article_features): + """ + Assess computational complexity of articles. + + Args: + article_features: List of computational features + + Returns: + dict: Complexity assessment + """ + complexity_scores = { + 'interactive_plots': 1, + 'data_analysis': 2, + 'machine_learning': 3, + 'large_datasets': 2, + 'real_time_computation': 3, + '3d_visualizations': 2, + 'multiple_notebooks': 1 + } + + total_score = sum(complexity_scores.get(feature, 0) for feature in article_features) + + if total_score <= 3: + return "Low complexity - Tier 1 suitable" + elif total_score <= 6: + return "Medium complexity - Tier 2 recommended" + else: + return "High complexity - Tier 3 recommended" +``` + +### Budget Considerations +```python +# Cost analysis +def estimate_compute_costs(tier, monthly_interactions, session_duration=0.75): + """ + Estimate monthly compute costs. + + Args: + tier: Compute tier (1, 2, or 3) + monthly_interactions: Number of interactive sessions per month + session_duration: Average session duration in hours + + Returns: + dict: Cost estimates + """ + # Base costs per tier (example values) + base_costs = { + 1: {'base': 100, 'per_session': 0.10}, + 2: {'base': 500, 'per_session': 0.25}, + 3: {'base': 1500, 'per_session': 0.50} + } + + tier_costs = base_costs.get(tier, base_costs[1]) + session_costs = monthly_interactions * session_duration * tier_costs['per_session'] + total_cost = tier_costs['base'] + session_costs + + return { + 'base_cost': tier_costs['base'], + 'session_costs': session_costs, + 'total_monthly_cost': total_cost, + 'cost_per_interaction': total_cost / monthly_interactions if monthly_interactions > 0 else 0 + } +``` + +## 4. Understand Resource Triggers + +Learn when and how compute resources are activated: + +### Static vs Interactive Content +```mermaid +graph TD + A[Article Content] --> B{Content Type} + B -->|Static Text| C[No Compute Required] + B -->|Static Images| C + B -->|Interactive Figures| D[Compute May Be Required] + B -->|Jupyter Notebooks| E[Compute Required] + B -->|Real-time Analysis| E + + D --> F{Self-contained} + F -->|Yes| G[No Compute - Works Offline] + F -->|No| E + + E --> H[Launch Compute Environment] + H --> I[45-minute Session] + I --> J[Resource Release] +``` + +### Interactive Content Types +```yaml +# Content classification +interactive_content: + no_compute_required: + - "Static interactive plots (Plotly, Altair)" + - "Pre-rendered visualizations" + - "Embedded data tables" + - "Static code examples" + + compute_required: + - "Jupyter notebook execution" + - "Real-time data analysis" + - "Dynamic model training" + - "Live data streaming" + - "Custom interactive widgets" + - "Server-side computations" +``` + +### Session Management +```python +# Session tracking example +class ComputeSession: + def __init__(self, user_id, article_id, tier): + self.user_id = user_id + self.article_id = article_id + self.tier = tier + self.start_time = time.time() + self.last_activity = time.time() + self.resources_allocated = self.allocate_resources() + + def allocate_resources(self): + """Allocate compute resources based on tier.""" + resource_limits = { + 1: {'cpu': '2 cores', 'memory': '4GB'}, + 2: {'cpu': '4 cores', 'memory': '8GB'}, + 3: {'cpu': '8 cores', 'memory': '16GB'} + } + return resource_limits.get(self.tier, resource_limits[1]) + + def check_timeout(self, timeout_minutes=45): + """Check if session has timed out.""" + idle_time = time.time() - self.last_activity + return idle_time > (timeout_minutes * 60) + + def release_resources(self): + """Release allocated compute resources.""" + # Implementation for resource cleanup + pass +``` + +## 5. Configure Your Compute Environment + +Set up your computational environment for the chosen tier: + +### Environment Configuration +```yaml +# curvenote.yml with compute settings +version: 1 +project: + title: "Your Computational Article" + description: "Research with interactive computational features" + + # Compute tier configuration + compute: + tier: 2 # 1, 2, or 3 + environment: "environment.yml" + resources: + cpu: "4 cores" + memory: "8GB" + storage: "20GB" + + # Session settings + session: + timeout: 2700 # 45 minutes in seconds + max_concurrent: 25 + auto_scale: false + + # BinderHub settings + binderhub: + enabled: true + private: true + image_storage: true +``` + +### BinderHub Configuration +```yaml +# .binder/environment.yml +name: computational-article +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - pandas>=1.5.0 + - numpy>=1.21.0 + - matplotlib>=3.5.0 + - plotly>=5.0.0 + - altair>=4.2.0 + - jupyterlab>=3.5.0 + - scipy>=1.9.0 + - scikit-learn>=1.1.0 + - pip + - pip: + - jupyterlab-myst>=0.2.0 + - myst-nb>=0.17.0 + # System dependencies for complex computations + - gcc + - gfortran + - libopenblas-dev + - liblapack-dev +``` + +### Resource Optimization +```python +# Resource optimization utilities +def optimize_for_tier(data, tier): + """Optimize data and computations for specific tier.""" + optimizations = { + 1: { + 'max_data_size': '100MB', + 'max_points': 10000, + 'sampling': True, + 'caching': True + }, + 2: { + 'max_data_size': '500MB', + 'max_points': 50000, + 'sampling': False, + 'caching': True + }, + 3: { + 'max_data_size': '2GB', + 'max_points': 200000, + 'sampling': False, + 'caching': True + } + } + + return optimizations.get(tier, optimizations[1]) + +def create_tier_optimized_plot(data, tier): + """Create plots optimized for specific tier.""" + config = optimize_for_tier(data, tier) + + if config['sampling'] and len(data) > config['max_points']: + data = data.sample(n=config['max_points'], random_state=42) + + # Create plot with tier-appropriate settings + fig = px.scatter(data, x='x', y='y') + + if config['caching']: + # Enable caching for better performance + fig.update_layout( + uirevision='constant', # Maintain zoom/pan state + dragmode='select' + ) + + return fig +``` + +## 6. Monitor and Optimize Usage + +Track and optimize your compute resource usage: + +### Usage Monitoring +```python +# Usage monitoring utilities +class ComputeMonitor: + def __init__(self, tier): + self.tier = tier + self.usage_stats = { + 'total_sessions': 0, + 'active_sessions': 0, + 'total_compute_time': 0, + 'peak_concurrent_users': 0 + } + + def track_session_start(self, user_id): + """Track when a new session starts.""" + self.usage_stats['total_sessions'] += 1 + self.usage_stats['active_sessions'] += 1 + self.usage_stats['peak_concurrent_users'] = max( + self.usage_stats['peak_concurrent_users'], + self.usage_stats['active_sessions'] + ) + + def track_session_end(self, duration): + """Track when a session ends.""" + self.usage_stats['active_sessions'] -= 1 + self.usage_stats['total_compute_time'] += duration + + def get_utilization_rate(self): + """Calculate resource utilization rate.""" + tier_limits = { + 1: 10, # Max concurrent users for Tier 1 + 2: 25, # Max concurrent users for Tier 2 + 3: 50 # Max concurrent users for Tier 3 + } + + max_users = tier_limits.get(self.tier, 10) + return self.usage_stats['active_sessions'] / max_users +``` + +### Performance Metrics +```python +# Performance tracking +def track_performance_metrics(session_data): + """Track performance metrics for compute sessions.""" + metrics = { + 'startup_time': [], + 'response_time': [], + 'error_rate': 0, + 'success_rate': 0 + } + + for session in session_data: + metrics['startup_time'].append(session['startup_time']) + metrics['response_time'].append(session['response_time']) + + if session['status'] == 'error': + metrics['error_rate'] += 1 + else: + metrics['success_rate'] += 1 + + # Calculate averages + metrics['avg_startup_time'] = np.mean(metrics['startup_time']) + metrics['avg_response_time'] = np.mean(metrics['response_time']) + metrics['error_rate'] = metrics['error_rate'] / len(session_data) + metrics['success_rate'] = metrics['success_rate'] / len(session_data) + + return metrics +``` + +### Cost Optimization +```python +# Cost optimization strategies +def optimize_compute_costs(usage_data, tier): + """Optimize compute costs based on usage patterns.""" + recommendations = [] + + # Analyze usage patterns + peak_hours = usage_data['peak_hours'] + off_peak_usage = usage_data['off_peak_usage'] + + if tier == 1 and peak_hours > 80: + recommendations.append("Consider upgrading to Tier 2 for better performance") + + if tier == 2 and off_peak_usage < 20: + recommendations.append("Consider downgrading to Tier 1 to reduce costs") + + if tier == 2 and peak_hours > 90: + recommendations.append("Consider upgrading to Tier 3 for scalability") + + return recommendations +``` + +## 7. Plan for Scaling + +Prepare for growth and changing computational needs: + +### Scaling Strategies +```yaml +# Scaling considerations +scaling_strategies: + tier1_to_tier2: + triggers: + - "Consistent performance issues" + - "Frequent resource exhaustion" + - "User complaints about slow response" + - "Peak concurrent users > 8" + + benefits: + - "Improved performance consistency" + - "Dedicated resources" + - "Better availability" + - "Custom scaling options" + + tier2_to_tier3: + triggers: + - "High traffic periods" + - "Complex computational workflows" + - "Real-time requirements" + - "Peak concurrent users > 20" + + benefits: + - "Maximum performance" + - "Auto-scaling capabilities" + - "Highest availability" + - "Cost-effective at scale" +``` + +### Migration Planning +```python +# Migration planning utilities +def plan_tier_migration(current_tier, target_tier, usage_data): + """Plan migration between compute tiers.""" + migration_plan = { + 'current_tier': current_tier, + 'target_tier': target_tier, + 'migration_steps': [], + 'estimated_downtime': 0, + 'cost_impact': 0 + } + + if current_tier == 1 and target_tier == 2: + migration_plan['migration_steps'] = [ + "1. Schedule maintenance window", + "2. Update curvenote.yml configuration", + "3. Test new environment", + "4. Migrate active sessions", + "5. Update DNS/routing" + ] + migration_plan['estimated_downtime'] = "15 minutes" + + elif current_tier == 2 and target_tier == 3: + migration_plan['migration_steps'] = [ + "1. Plan cluster deployment", + "2. Set up load balancing", + "3. Configure auto-scaling", + "4. Migrate data and configurations", + "5. Update monitoring and alerts" + ] + migration_plan['estimated_downtime'] = "30 minutes" + + return migration_plan +``` + +## 8. Contact and Consultation + +Get help choosing and implementing the right compute tier: + +### Consultation Process +```mermaid +graph TD + A[Contact Curvenote] --> B[Initial Assessment] + B --> C[Requirements Analysis] + C --> D[Tier Recommendation] + D --> E[Implementation Planning] + E --> F[Environment Setup] + F --> G[Testing & Validation] + G --> H[Go Live] + H --> I[Ongoing Support] +``` + +### Contact Information +```markdown +## Get Started with Compute Tiers + +### Consultation Request +- **Email**: [compute@curvenote.com](mailto:compute@curvenote.com) +- **Demo**: [Schedule a consultation](https://curvenote.com/demo) +- **Documentation**: [Compute Services Guide](https://docs.curvenote.com/compute) + +### What to Prepare +- Current traffic patterns and user interaction data +- Computational requirements and complexity assessment +- Budget considerations and scaling expectations +- Timeline for implementation +- Technical requirements and constraints +``` + +### Implementation Timeline +```yaml +# Typical implementation timeline +implementation_timeline: + week_1: + - "Initial consultation and requirements gathering" + - "Tier selection and configuration planning" + + week_2: + - "Environment setup and testing" + - "Configuration optimization" + + week_3: + - "Integration with existing infrastructure" + - "Performance testing and validation" + + week_4: + - "Go-live preparation" + - "Monitoring setup and alert configuration" + + ongoing: + - "Performance monitoring and optimization" + - "Scaling consultations as needed" +``` + +## Next Steps + +- [Learn about Computational Best Practices →](./best-practices.md) +- [Create Computational Articles →](./computational-articles.md) +- [Create Interactive Figures →](./interactive-figures.md) +- [Embed Notebooks in Computational Content →](./embed-notebooks.md) +- [Understand Live Compute →](../live-compute.md) + +--- + +💡 **Tip:** Start with Tier 1 for new projects and scale up based on actual usage patterns and user feedback. Follow these compute tier best practices: + +- **Start small**: Begin with Tier 1 and scale based on actual needs +- **Monitor usage**: Track performance metrics and user satisfaction +- **Plan for growth**: Consider scaling requirements when choosing initial tier +- **Optimize costs**: Balance performance needs with budget constraints +- **Test thoroughly**: Validate computational workflows before going live +- **Document requirements**: Clearly document computational needs for consultation diff --git a/Computational/embed-notebooks.md b/Computational/embed-notebooks.md new file mode 100644 index 0000000..8529e1b --- /dev/null +++ b/Computational/embed-notebooks.md @@ -0,0 +1,391 @@ +--- +title: Embed Notebooks in Computational Content +short_title: Embed Notebooks +--- + +# Embed Notebooks in Computational Content + +## Overview +Integrate Jupyter notebooks into your Curvenote articles and reports to create rich, interactive computational content + +Embedding notebooks allows you to combine narrative text with executable code, interactive visualizations, and computational outputs. Curvenote provides seamless integration between Jupyter notebooks and articles, enabling you to create computational articles and reports that maintain the full power of Jupyter while providing a structured, publication-ready format. + +## Before You Start + +Make sure you have: +- A Curvenote project with computational content +- Jupyter notebooks (`.ipynb` files) ready to embed +- Understanding of notebook cell types and structure +- Access to the Curvenote editor interface +- Knowledge of MyST Markdown syntax + +## 1. Understand Notebook Integration + +Learn how notebooks work with Curvenote: + +### Notebook Cell Types +Curvenote recognizes three types of Jupyter notebook cells: + +**Code Cells**: +- Contain executable code (Python, R, Julia, etc.) +- Can only be edited and run in Jupyter +- Display as read-only in Curvenote articles +- Produce output cells when executed + +**Output Cells**: +- Contain results from code execution +- Can include text, images, tables, or interactive plots +- Automatically linked to their code cells +- Can be imported as figures in articles + +**Markdown Cells**: +- Contain rich text and documentation +- Can be edited in both Jupyter and Curvenote +- Support MyST Markdown syntax +- Integrate seamlessly with article content + +### Integration Workflow +```mermaid +graph LR + A[Jupyter Notebook] --> B[Upload to Curvenote] + B --> C[Edit in Curvenote] + C --> D[Import Cells to Articles] + D --> E[Publish Computational Content] +``` + +## 2. Upload and Link Notebooks + +Add your Jupyter notebooks to Curvenote: + +### Upload Pre-Executed Notebooks +```{important} +Always upload pre-executed notebooks to Curvenote so that outputs are visible and available for use. +``` + +**Step 1: Prepare Your Notebook** +1. **Execute all cells** in Jupyter Lab or Jupyter Notebook +2. **Save the notebook** with outputs included +3. **Verify all outputs** are displayed correctly + +**Step 2: Upload to Curvenote** +1. **Navigate to your project** in Curvenote +2. **Click the Upload icon** (☁️⬆️) in the project panel +3. **Drag and drop** your `.ipynb` file or click to browse +4. **Click "DONE"** to complete the upload + +```{figure} images/m59m7JQmWVyPjlASj9v3-UGpUYCC2QlQIhNSTYmEh-v1.mp4 +:name: upload-notebook +:align: center +:width: 100% +``` + +### Link Local Notebooks +For notebooks you want to continue editing: + +**Step 1: Link Existing Notebook** +1. **Copy the OXA link** from your Curvenote notebook +2. **Open your local Jupyter environment** +3. **Use the link** to establish the connection + +**Step 2: Sync Changes** +```bash +# In your local Jupyter environment +# Make changes to your notebook +# Save the notebook +# Changes will sync to Curvenote +``` + +## 3. Import Notebook Cells + +Bring notebook content into your articles: + +### Import Output Cells as Figures +```{tip} +Output cells from notebooks can be imported as figures in your articles, maintaining their interactive properties. +``` + +**Step 1: Copy Cell Link** +1. **Open your notebook** in Curvenote +2. **Select the output cell** you want to import +3. **Click the ⋮ Options menu** in the upper right +4. **Select "Copy Link"** + +**Step 2: Import into Article** +1. **Open your article** in Draft Mode +2. **Select the location** where you want the cell +3. **Paste the link** and press Enter +4. **The cell appears** as a block in your article + +### Import Code Cells +```python +# Code cells can be imported for reference +# They will display as read-only code blocks +import pandas as pd +import matplotlib.pyplot as plt + +# Your computational code here +data = pd.read_csv('experiment_data.csv') +plt.plot(data['x'], data['y']) +plt.show() +``` + +### Import Markdown Cells +```{myst} +# Markdown cells integrate seamlessly with articles +# They can be edited in both Jupyter and Curvenote + +## Analysis Results + +Our computational analysis revealed significant patterns in the data. +The results are shown in the interactive plot below. +``` + +## 4. Create Interactive Visualizations + +Embed interactive plots and outputs: + +### Supported Interactive Libraries +Curvenote supports interactive outputs from these libraries: + +**Python Libraries**: +- **Plotly**: Interactive plots with zoom, pan, hover +- **Altair**: Declarative statistical visualizations +- **Bokeh**: Interactive web plots and dashboards +- **Matplotlib**: Static plots with publication quality +- **Seaborn**: Statistical data visualization +- **Pandas**: Interactive data tables + +**R Libraries**: +- **Plotly**: Interactive R plots +- **ggplot2**: Static statistical plots +- **DT**: Interactive data tables +- **Leaflet**: Interactive maps + +### Create Interactive Plots +```python +# Example: Create interactive Plotly plot +import plotly.express as px +import pandas as pd + +# Load data +data = pd.read_csv('experiment_results.csv') + +# Create interactive scatter plot +fig = px.scatter(data, x='x_value', y='y_value', + color='category', size='magnitude', + hover_data=['condition', 'time'], + title='Interactive Experimental Results') + +fig.show() +``` + +### Embed in Articles +```{myst} +## Results + +Our analysis produced the following interactive visualization: + +[Interactive plot will appear here when imported from notebook] + +The plot shows significant differences between experimental conditions. +``` + +## 5. Structure Computational Articles + +Organize your content effectively: + +### Article Structure with Embedded Notebooks +```{myst} +# Computational Article Title + +## Abstract + +Brief summary of your computational research. + +## Introduction + +Background and research objectives. + +## Methods + +### Data Processing +[Import code cell showing data loading and preprocessing] + +### Analysis Pipeline +[Import code cell showing analysis steps] + +## Results + +### Interactive Visualizations +[Import output cell with interactive plot] + +### Statistical Analysis +[Import output cell with statistical results] + +## Discussion + +Interpretation of results and implications. + +## Code Availability + +The complete analysis is available in the embedded notebook. +``` + +### Mixed Content Approach +```{myst} +## Data Analysis + +We analyzed the experimental dataset using Python's pandas library. + +```{code-cell} python +# Import and process data +import pandas as pd +import numpy as np + +data = pd.read_csv('experiment_data.csv') +print(f"Dataset shape: {data.shape}") +print(f"Columns: {list(data.columns)}") +``` + +The analysis revealed three key findings: + +1. **Finding 1**: Description of the first result +2. **Finding 2**: Description of the second result +3. **Finding 3**: Description of the third result + +[Interactive visualization imported from notebook output cell] +``` + +## 6. Version Control and Collaboration + +Manage notebook versions and collaborate effectively: + +### Version Control +```{important} +Each notebook cell is versioned individually in Curvenote, allowing for precise tracking of changes. +``` + +**Cell Versioning**: +- **Individual cell versions**: Track changes to specific cells +- **Notebook versions**: Save complete notebook states +- **Cross-references**: Link to specific cell versions + +**Version Management**: +1. **Save cell versions** as you develop +2. **Track changes** through version history +3. **Revert to previous versions** if needed +4. **Compare versions** to see differences + +### Collaboration Features +```{myst} +## Collaborative Workflow + +1. **Share notebooks** with collaborators +2. **Edit markdown cells** in Curvenote +3. **Edit code cells** in Jupyter +4. **Sync changes** automatically +5. **Review and approve** versions +``` + +## 7. Configure Computational Environment + +Set up your project for notebook integration: + +### Project Configuration +```yaml +# curvenote.yml +version: 1 +project: + title: "My Computational Article" + description: "Research with embedded Jupyter notebooks" + + # Enable Jupyter features + jupyter: true + + # Export formats + exports: + - format: meca + - format: pdf + - format: typst + + # Dependencies + requirements: + - requirements.txt + - environment.yml + + # Resources + resources: + - notebooks/*.ipynb + - data/processed/* + - src/**/* + + # Computational settings + computational: + binderhub: true + jupyter: true +``` + +### Environment Dependencies +```txt +# requirements.txt +pandas>=1.5.0 +numpy>=1.21.0 +matplotlib>=3.5.0 +seaborn>=0.11.0 +plotly>=5.0.0 +altair>=4.2.0 +jupyterlab>=3.5.0 +jupyterlab-myst>=0.2.0 +``` + +## 8. Best Practices + +Follow these guidelines for effective notebook embedding: + +### Notebook Preparation +- **Execute all cells** before uploading +- **Clear outputs** if notebooks are large +- **Use descriptive cell names** for easy identification +- **Include comprehensive documentation** in markdown cells + +### Content Organization +- **Structure notebooks logically** with clear sections +- **Separate concerns** between different notebooks +- **Use consistent naming conventions** +- **Include setup and installation instructions** + +### Performance Optimization +- **Limit notebook size** for faster loading +- **Use efficient data structures** and algorithms +- **Cache expensive computations** when possible +- **Optimize interactive plots** for web display + +### Collaboration Guidelines +- **Document your workflow** clearly +- **Use version control** for all changes +- **Communicate changes** to collaborators +- **Test notebooks** in different environments + +### Publication Readiness +- **Ensure reproducibility** with proper dependencies +- **Include data sources** and citations +- **Provide clear instructions** for reproduction +- **Test the complete workflow** before publishing + +## Next Steps + +- [Learn about Computational Best Practices →](./best-practices.md) +- [Create Computational Articles →](../computational-articles.md) +- [Understand Live Compute →](../live-compute.md) +- [Explore Computational Tiers →](../computational-tiers.md) + +--- + +💡 **Tip:** Start with simple notebook embedding and gradually add complexity. Always test your embedded notebooks in the final publication environment. Follow these notebook embedding best practices: + +- **Pre-execute notebooks**: Always upload notebooks with outputs included +- **Version control**: Use Curvenote's versioning for tracking changes +- **Interactive content**: Leverage supported libraries for engaging visualizations +- **Performance**: Optimize notebooks for web display and loading +- **Collaboration**: Use shared workflows for team development +- **Reproducibility**: Ensure all dependencies and data sources are documented diff --git a/Computational/interactive-figures.md b/Computational/interactive-figures.md new file mode 100644 index 0000000..d5f2727 --- /dev/null +++ b/Computational/interactive-figures.md @@ -0,0 +1,540 @@ +--- +title: Create Interactive Figures +short_title: Interactive Figures +--- + +# Create Interactive Figures + +## Overview +Create engaging, interactive visualizations that enhance your computational research and provide readers with dynamic exploration capabilities + +Interactive figures transform static research visualizations into dynamic, explorable content that allows readers to zoom, pan, hover, and interact with your data. Curvenote supports a wide range of interactive plotting libraries, enabling you to create publication-quality interactive visualizations that work seamlessly in both Jupyter notebooks and published articles. + +## Before You Start + +Make sure you have: +- A Curvenote project with computational content +- Jupyter environment set up with interactive plotting libraries +- Data ready for visualization +- Understanding of your target audience and interaction needs +- Knowledge of supported plotting libraries + +## 1. Choose Your Interactive Library + +Select the right library for your visualization needs: + +### Supported Python Libraries + +**Plotly** - Most Popular Choice: +- **Best for**: Interactive web plots, dashboards, complex visualizations +- **Features**: Zoom, pan, hover, selection, animations +- **Use cases**: Scatter plots, line charts, 3D plots, heatmaps +- **Installation**: `pip install plotly` + +**Altair** - Declarative Statistical Plots: +- **Best for**: Statistical visualizations, data exploration +- **Features**: Grammar of graphics, automatic interactivity +- **Use cases**: Scatter plots, bar charts, histograms, faceted plots +- **Installation**: `pip install altair vega_datasets` + +**Bokeh** - Interactive Web Plots: +- **Best for**: Complex dashboards, real-time data +- **Features**: Custom interactions, streaming data, server integration +- **Use cases**: Time series, geographic plots, custom widgets +- **Installation**: `pip install bokeh` + +**Matplotlib/Seaborn** - Static with Interactive Elements: +- **Best for**: Publication-quality static plots with basic interactivity +- **Features**: High-quality output, extensive customization +- **Use cases**: Scientific figures, statistical plots +- **Installation**: `pip install matplotlib seaborn` + +### Supported R Libraries + +**Plotly for R**: +- **Best for**: Interactive R plots +- **Features**: Same capabilities as Python Plotly +- **Installation**: `install.packages("plotly")` + +**ggplot2 with plotly**: +- **Best for**: Grammar of graphics with interactivity +- **Features**: Convert ggplot2 to interactive plots +- **Installation**: `install.packages(c("ggplot2", "plotly"))` + +**DT (DataTables)**: +- **Best for**: Interactive data tables +- **Features**: Sorting, filtering, pagination +- **Installation**: `install.packages("DT")` + +## 2. Create Basic Interactive Plots + +Start with fundamental interactive visualizations: + +### Plotly Scatter Plot +```python +import plotly.express as px +import pandas as pd + +# Load sample data +data = pd.read_csv('experiment_data.csv') + +# Create interactive scatter plot +fig = px.scatter(data, + x='x_value', + y='y_value', + color='category', + size='magnitude', + hover_data=['condition', 'time'], + title='Interactive Scatter Plot') + +# Customize layout +fig.update_layout( + xaxis_title="X Variable", + yaxis_title="Y Variable", + font=dict(size=12), + hovermode='closest' +) + +fig.show() +``` + +### Altair Statistical Plot +```python +import altair as alt +import pandas as pd + +# 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() + +# Add title and properties +chart = chart.properties( + title='Interactive Statistical Visualization', + width=600, + height=400 +) + +chart +``` + +### Bokeh Interactive Plot +```python +from bokeh.plotting import figure, show +from bokeh.io import output_notebook +import pandas as pd + +# Enable notebook output +output_notebook() + +# Create Bokeh figure +p = figure(title="Interactive Bokeh Plot", + x_axis_label='X Variable', + y_axis_label='Y Variable', + tools="pan,box_zoom,wheel_zoom,reset,save") + +# Add scatter plot +p.scatter(data['x_value'], data['y_value'], + size=8, alpha=0.6, color='blue') + +show(p) +``` + +## 3. Advanced Interactive Features + +Enhance your visualizations with advanced interactive capabilities: + +### Multi-Panel Interactive Plots +```python +import plotly.graph_objects as go +from plotly.subplots import make_subplots + +# Create subplots +fig = make_subplots( + rows=2, cols=2, + subplot_titles=('Scatter Plot', 'Line Plot', 'Histogram', 'Box Plot'), + specs=[[{"secondary_y": False}, {"secondary_y": False}], + [{"secondary_y": False}, {"secondary_y": False}]] +) + +# Add scatter plot +fig.add_trace( + go.Scatter(x=data['x_value'], y=data['y_value'], + mode='markers', name='Scatter'), + row=1, col=1 +) + +# Add line plot +fig.add_trace( + go.Scatter(x=data['time'], y=data['value'], + mode='lines', name='Time Series'), + row=1, col=2 +) + +# Add histogram +fig.add_trace( + go.Histogram(x=data['value'], name='Distribution'), + row=2, col=1 +) + +# Add box plot +fig.add_trace( + go.Box(y=data['value'], name='Box Plot'), + row=2, col=2 +) + +fig.update_layout(height=800, title_text="Multi-Panel Interactive Plot") +fig.show() +``` + +### Interactive Time Series +```python +import plotly.graph_objects as go + +# Create time series plot +fig = go.Figure() + +# Add traces for different conditions +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}
Value: %{y}
Condition: ' + condition + )) + +# Update layout +fig.update_layout( + title='Interactive Time Series Analysis', + xaxis_title='Time', + yaxis_title='Value', + hovermode='x unified', + showlegend=True +) + +fig.show() +``` + +### 3D Interactive Plots +```python +import plotly.graph_objects as go + +# Create 3D scatter plot +fig = go.Figure(data=[go.Scatter3d( + x=data['x_value'], + y=data['y_value'], + z=data['z_value'], + mode='markers', + marker=dict( + size=8, + color=data['category'], + colorscale='Viridis', + opacity=0.8 + ), + text=data['condition'], + hovertemplate='X: %{x}
Y: %{y}
Z: %{z}
Condition: %{text}' +)]) + +fig.update_layout( + title='3D Interactive Scatter Plot', + scene=dict( + xaxis_title='X Variable', + yaxis_title='Y Variable', + zaxis_title='Z Variable' + ) +) + +fig.show() +``` + +## 4. Customize Interactive Behavior + +Tailor interactions to your specific needs: + +### Custom Hover Information +```python +import plotly.express as px + +# Create custom hover template +fig = px.scatter(data, x='x_value', y='y_value', color='category') + +fig.update_traces( + hovertemplate="Point Details
" + + "X: %{x:.2f}
" + + "Y: %{y:.2f}
" + + "Category: %{marker.color}
" + + "" +) + +fig.show() +``` + +### Interactive Selection and Filtering +```python +import plotly.express as px +from plotly.subplots import make_subplots + +# Create linked subplots +fig = make_subplots(rows=1, cols=2) + +# Main scatter plot +fig.add_trace( + go.Scatter(x=data['x_value'], y=data['y_value'], + mode='markers', name='Main Plot', + selectedpoints=[], + selected=dict(marker=dict(color='red')), + unselected=dict(marker=dict(color='blue', opacity=0.3))), + row=1, col=1 +) + +# Histogram of selected points +fig.add_trace( + go.Histogram(x=data['x_value'], name='Distribution'), + row=1, col=2 +) + +fig.update_layout( + title='Interactive Selection Plot', + dragmode='select' +) + +fig.show() +``` + +### Animation and Transitions +```python +import plotly.express as px + +# Create animated scatter plot +fig = px.scatter(data, x='x_value', y='y_value', + color='category', animation_frame='time', + size='magnitude', hover_name='condition') + +fig.update_layout( + title='Animated Interactive Plot', + updatemenus=[dict( + type="buttons", + showactive=False, + buttons=[dict(label="Play", + method="animate", + args=[None, {"frame": {"duration": 500, "redraw": True}, + "fromcurrent": True}])] + )] +) + +fig.show() +``` + +## 5. Performance Optimization + +Optimize your interactive plots for web display: + +### Efficient Data Handling +```python +def create_efficient_plot(data, max_points=10000): + """Create efficient interactive plot for large datasets.""" + + # Sample data if too large + if len(data) > max_points: + plot_data = data.sample(n=max_points, random_state=42) + title_suffix = f" (showing {max_points:,} of {len(data):,} points)" + else: + plot_data = data + title_suffix = "" + + # Create plot + fig = px.scatter(plot_data, x='x_value', y='y_value', + color='category', size='magnitude', + title=f'Interactive Plot{title_suffix}') + + return fig + +# Use the function +fig = create_efficient_plot(large_dataset, max_points=5000) +fig.show() +``` + +### Lazy Loading for Large Datasets +```python +import plotly.graph_objects as go + +def create_lazy_loading_plot(data, chunk_size=1000): + """Create plot with lazy loading for very large datasets.""" + + # Create initial plot with first chunk + initial_data = data.head(chunk_size) + + fig = go.Figure(data=go.Scatter( + x=initial_data['x_value'], + y=initial_data['y_value'], + mode='markers', + name='Data Points' + )) + + # Add loading indicator + fig.update_layout( + title='Large Dataset Plot (Lazy Loading)', + updatemenus=[{ + 'buttons': [{ + 'label': 'Load More Data', + 'method': 'restyle', + 'args': [{'x': [data['x_value'][:chunk_size*2]], + 'y': [data['y_value'][:chunk_size*2]]}] + }], + 'direction': 'down', + 'showactive': True, + }] + ) + + return fig +``` + +## 6. Embed in Curvenote Articles + +Integrate interactive figures into your computational content: + +### Import from Jupyter Notebooks +```{myst} +## Results + +Our analysis produced the following interactive visualization: + +[Interactive plot imported from notebook output cell] + +The plot shows significant differences between experimental conditions. +``` + +### Reference Interactive Figures +```{myst} +## Interactive Analysis + +As shown in the interactive plot above, the data reveals clear patterns. +Readers can zoom, pan, and hover over data points to explore the results. + +### Key Findings + +1. **Pattern 1**: Description of the first pattern visible in the interactive plot +2. **Pattern 2**: Description of the second pattern visible in the interactive plot +3. **Pattern 3**: Description of the third pattern visible in the interactive plot +``` + +### Cross-Reference Interactive Content +```{myst} +## Discussion + +The interactive visualization in {numref}`Figure %s ` +allows readers to explore the data in detail. Users can: + +- **Zoom in** on specific regions of interest +- **Hover over points** to see detailed information +- **Filter by category** to focus on specific groups +- **Export the plot** for further analysis +``` + +## 7. Best Practices + +Follow these guidelines for effective interactive figures: + +### Design Principles +- **Purpose-driven**: Ensure interactivity adds value to understanding +- **Intuitive**: Make interactions obvious and discoverable +- **Performance**: Optimize for smooth interaction experience +- **Accessibility**: Provide alternative static versions when needed + +### Technical Guidelines +- **Pre-execute notebooks**: Always include outputs when uploading +- **Test interactions**: Verify all interactive features work correctly +- **Optimize data size**: Use sampling or aggregation for large datasets +- **Provide context**: Include clear titles, labels, and descriptions + +### Publication Considerations +- **Static fallbacks**: Ensure content is readable without interactivity +- **Cross-platform**: Test on different browsers and devices +- **Loading times**: Optimize for reasonable load times +- **Documentation**: Provide instructions for using interactive features + +### Library-Specific Tips + +**Plotly**: +- Use `fig.update_layout()` for consistent styling +- Leverage `fig.update_traces()` for bulk updates +- Consider using `fig.write_html()` for standalone files + +**Altair**: +- Use the grammar of graphics for consistent plots +- Leverage automatic interactivity features +- Combine with `altair_saver` for static exports + +**Bokeh**: +- Use `output_notebook()` for Jupyter integration +- Leverage custom callbacks for advanced interactions +- Consider Bokeh server for real-time updates + +## 8. Troubleshooting + +Handle common issues with interactive figures: + +### Common Problems and Solutions + +**Plot Not Displaying**: +```python +# Check if plotly is properly installed +import plotly +print(plotly.__version__) + +# Ensure proper output mode +import plotly.io as pio +pio.renderers.default = "notebook" +``` + +**Performance Issues**: +```python +# Reduce data size for better performance +def optimize_for_web(data, max_points=5000): + if len(data) > max_points: + return data.sample(n=max_points, random_state=42) + return data + +# Use efficient data types +data = data.astype({ + 'category': 'category', + 'value': 'float32' +}) +``` + +**Interactive Features Not Working**: +```python +# Ensure proper hover configuration +fig.update_traces( + hoverinfo='all', + hovertemplate='%{fullData.name}
' + + 'X: %{x}
' + + 'Y: %{y}
' + + '' +) +``` + +## Next Steps + +- [Learn about Computational Best Practices →](./best-practices.md) +- [Embed Notebooks in Computational Content →](./embed-notebooks.md) +- [Understand Live Compute →](../live-compute.md) +- [Explore Computational Tiers →](../computational-tiers.md) + +--- + +💡 **Tip:** Start with simple interactive plots and gradually add complexity. Always test your interactive figures in the final publication environment. Follow these interactive figure best practices: + +- **Purpose-driven design**: Ensure interactivity enhances understanding +- **Performance optimization**: Optimize for smooth user experience +- **Accessibility**: Provide alternatives for non-interactive environments +- **Testing**: Verify all interactive features work across platforms +- **Documentation**: Provide clear instructions for using interactive features +- **Fallbacks**: Ensure content is readable without interactivity +::: diff --git a/editor/interactive-outputs-in-jupyter.md b/Computational/interactive-outputs-in-jupyter.md similarity index 100% rename from editor/interactive-outputs-in-jupyter.md rename to Computational/interactive-outputs-in-jupyter.md diff --git a/Computational/live-compute.md b/Computational/live-compute.md new file mode 100644 index 0000000..929647f --- /dev/null +++ b/Computational/live-compute.md @@ -0,0 +1,715 @@ +--- +title: Live Compute +short_title: Live Compute +--- + +# Live Compute + +## Overview +Set up and configure live computational environments using BinderHub and REES for interactive, reproducible research articles and reports + +Live compute enables readers to interact with your computational content in real-time, executing code, exploring data, and running analyses directly within your published articles. Curvenote uses a private BinderHub infrastructure with REES (Reproducible Execution Environment Specification) to provide fast, secure, and reliable computational environments that enhance the reproducibility and interactivity of your research. + +## Before You Start + +Make sure you have: +- A Curvenote project with computational content +- Understanding of BinderHub and REES concepts +- Python or R environment management experience +- Knowledge of dependency management files (requirements.txt, environment.yml) +- Access to GitHub for testing on mybinder.org +- Curvenote CLI installed for local testing + +## 1. Understand Live Compute Infrastructure + +Learn how Curvenote's live compute system works: + +### BinderHub and REES Overview +```yaml +# Live Compute Infrastructure +live_compute: + infrastructure: "Private BinderHub" + specification: "REES (Reproducible Execution Environment Specification)" + caching: "Pre-stored images for fast startup" + isolation: "Secure, isolated computational environments" + scalability: "On-demand resource allocation" +``` + +### Architecture Components +```mermaid +flowchart TD + A[Reader Requests Compute] --> B[Curvenote Private BinderHub] + B --> C[REES Configuration Files] + C --> D[Environment Build] + D --> E[Image Caching] + E --> F[Live JupyterLab Session] + F --> G[Interactive Execution] + G --> H[Session Timeout] + H --> I[Resource Cleanup] +``` + +### REES Configuration Files +```python +# REES file types and purposes +rees_files = { + 'requirements.txt': 'Python package dependencies', + 'environment.yml': 'Conda environment specification', + 'apt.txt': 'System-level dependencies', + 'postBuild': 'Post-build setup scripts', + 'start': 'Custom startup commands', + 'runtime.txt': 'Python version specification', + 'install.R': 'R package installation', + 'DESCRIPTION': 'R package metadata' +} +``` + +## 2. Set Up Your Computational Environment + +Create a reproducible environment for your research: + +### Python Environment Configuration +```yaml +# environment.yml +name: computational-research +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - pandas>=1.5.0 + - numpy>=1.21.0 + - matplotlib>=3.5.0 + - seaborn>=0.11.0 + - plotly>=5.0.0 + - altair>=4.2.0 + - jupyterlab>=3.5.0 + - scipy>=1.9.0 + - scikit-learn>=1.1.0 + - pip + - pip: + - jupyterlab-myst>=0.2.0 + - myst-nb>=0.17.0 + - ipywidgets>=7.6.0 +``` + +### Requirements File Alternative +```txt +# requirements.txt +pandas>=1.5.0 +numpy>=1.21.0 +matplotlib>=3.5.0 +seaborn>=0.11.0 +plotly>=5.0.0 +altair>=4.2.0 +jupyterlab>=3.5.0 +scipy>=1.9.0 +scikit-learn>=1.1.0 +jupyterlab-myst>=0.2.0 +myst-nb>=0.17.0 +ipywidgets>=7.6.0 +``` + +### System Dependencies +```txt +# apt.txt +gcc +gfortran +libopenblas-dev +liblapack-dev +libhdf5-dev +libnetcdf-dev +``` + +### R Environment Setup +```r +# install.R +install.packages(c( + "tidyverse", + "ggplot2", + "dplyr", + "plotly", + "DT", + "rmarkdown", + "knitr" +)) +``` + +### Custom Build Scripts +```bash +# postBuild +#!/bin/bash +# Install additional packages or setup custom configurations +pip install --no-deps custom-package +R -e "install.packages('custom-r-package')" +``` + +## 3. Configure MyST Markdown Support + +Enable MyST Markdown rendering in your computational environment: + +### Add MyST Support +```yaml +# environment.yml with MyST support +name: computational-research +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - jupyterlab>=3.5.0 + - pip + - pip: + - jupyterlab-myst>=0.2.0 + - myst-nb>=0.17.0 + - myst-parser>=0.18.0 +``` + +### MyST Configuration +```python +# myst_nb_config.py +# MyST-NB configuration for enhanced rendering +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "deflist", + "dollarmath", + "html_image", + "html_admonition", + "replacements", + "smartquotes", + "substitution", + "tasklist" +] + +# Enable execution of notebooks +jupyter_execute_notebooks = "auto" +execution_excludepatterns = ["_build/*", "binder/*", ".*"] +``` + +### JupyterLab Extensions +```python +# jupyter_config.py +# JupyterLab configuration for MyST support +c.ServerApp.jpserver_extensions = { + 'jupyterlab_myst': True, + 'jupyterlab_git': True, + 'jupyterlab_lsp': True +} +``` + +## 4. Test on Public BinderHub + +Validate your environment on mybinder.org before deployment: + +### GitHub Repository Setup +```bash +# Initialize git repository +git init +git add . +git commit -m "Initial computational environment setup" + +# Create .gitignore +echo "*.ipynb_checkpoints/" >> .gitignore +echo "__pycache__/" >> .gitignore +echo "*.pyc" >> .gitignore +echo "_build/" >> .gitignore +echo "*.zip" >> .gitignore + +# Push to GitHub +git remote add origin https://github.com/yourusername/your-repo.git +git push -u origin main +``` + +### BinderHub URL Construction +```python +# Generate BinderHub URL +def create_binder_url(repo_url, branch="main", filepath=None): + """Create BinderHub URL for testing.""" + base_url = "https://mybinder.org/v2/gh" + + if filepath: + return f"{base_url}/{repo_url}/{branch}?filepath={filepath}" + else: + return f"{base_url}/{repo_url}/{branch}" + +# Example usage +repo = "yourusername/your-repo" +url = create_binder_url(repo, filepath="notebooks/main.ipynb") +print(f"BinderHub URL: {url}") +``` + +### Environment Validation +```python +# test_environment.py +import sys +import importlib + +def test_environment(): + """Test that all required packages are available.""" + required_packages = [ + 'pandas', 'numpy', 'matplotlib', 'seaborn', + 'plotly', 'altair', 'jupyterlab', 'scipy', + 'sklearn', 'jupyterlab_myst' + ] + + missing_packages = [] + + for package in required_packages: + try: + importlib.import_module(package) + print(f"✓ {package} is available") + except ImportError: + missing_packages.append(package) + print(f"✗ {package} is missing") + + if missing_packages: + print(f"\nMissing packages: {missing_packages}") + return False + else: + print("\nAll packages are available!") + return True + +if __name__ == "__main__": + test_environment() +``` + +## 5. Configure Curvenote Frontmatter + +Set up your Curvenote project for live compute: + +### Basic Configuration +```yaml +# curvenote.yml +version: 1 +project: + title: "Your Computational Article" + description: "Research with live computational capabilities" + + # Enable live compute + jupyter: true + + # Export formats + exports: + - format: meca + - format: pdf + - format: typst + + # REES configuration files + requirements: + - requirements.txt + - environment.yml + - apt.txt + + # Additional resources + resources: + - notebooks/*.ipynb + - data/processed/* + - src/**/* + - models/*.pkl +``` + +### Advanced Configuration +```yaml +# curvenote.yml with advanced settings +version: 1 +project: + title: "Advanced Computational Article" + description: "Complex research with multiple computational environments" + + # Live compute settings + jupyter: true + computational: true + + # Multiple environment support + environments: + - name: "main" + requirements: ["requirements.txt", "environment.yml"] + resources: ["notebooks/*", "data/*"] + + - name: "analysis" + requirements: ["analysis-requirements.txt"] + resources: ["analysis/*"] + + # Export configuration + exports: + - format: meca + - format: pdf + - format: typst + - format: html + + # Computational tier + compute: + tier: 2 + timeout: 2700 # 45 minutes + max_concurrent: 25 +``` + +### MyST Configuration +```yaml +# myst.yml +version: 1 +project: + title: "MyST Computational Article" + + # MyST-specific settings + myst: + enable_extensions: + - amsmath + - colon_fence + - deflist + - dollarmath + - html_image + - html_admonition + - replacements + - smartquotes + - substitution + - tasklist + + # Notebook execution + jupyter_execute_notebooks: "auto" + execution_excludepatterns: ["_build/*", "binder/*", ".*"] + + # Interactive elements + interactive_outputs: true + hover_tooltips: true +``` + +## 6. Test Your Environment Locally + +Validate your setup before submission: + +### Local MECA Export +```bash +# Export MECA archive for testing +curvenote export meca + +# Check the exported archive +ls -la _build/exports/ +unzip -l _build/exports/*.zip +``` + +### Environment Validation Script +```python +# validate_environment.py +import zipfile +import yaml +import os + +def validate_meca_archive(archive_path): + """Validate MECA archive contents.""" + with zipfile.ZipFile(archive_path, 'r') as zip_file: + contents = zip_file.namelist() + + # Check for required files + required_files = [ + 'requirements.txt', + 'environment.yml', + 'curvenote.yml' + ] + + missing_files = [] + for file in required_files: + if not any(file in content for content in contents): + missing_files.append(file) + + if missing_files: + print(f"Missing required files: {missing_files}") + return False + + # Check for notebooks + notebooks = [f for f in contents if f.endswith('.ipynb')] + if not notebooks: + print("No notebooks found in archive") + return False + + print(f"Found {len(notebooks)} notebooks") + print("MECA archive validation passed!") + return True + +def validate_curvenote_config(): + """Validate curvenote.yml configuration.""" + with open('curvenote.yml', 'r') as f: + config = yaml.safe_load(f) + + # Check required fields + required_fields = ['jupyter', 'exports', 'requirements'] + missing_fields = [] + + for field in required_fields: + if field not in config.get('project', {}): + missing_fields.append(field) + + if missing_fields: + print(f"Missing required fields: {missing_fields}") + return False + + # Check MECA export + exports = config['project'].get('exports', []) + meca_export = any(exp.get('format') == 'meca' for exp in exports) + + if not meca_export: + print("MECA export not configured") + return False + + print("Curvenote configuration validation passed!") + return True + +if __name__ == "__main__": + # Find MECA archive + build_dir = "_build/exports" + if os.path.exists(build_dir): + archives = [f for f in os.listdir(build_dir) if f.endswith('.zip')] + if archives: + validate_meca_archive(os.path.join(build_dir, archives[0])) + + validate_curvenote_config() +``` + +### Performance Testing +```python +# performance_test.py +import time +import psutil +import subprocess + +def test_environment_startup(): + """Test environment startup time.""" + start_time = time.time() + + # Simulate environment startup + try: + result = subprocess.run( + ['python', '-c', 'import pandas, numpy, matplotlib'], + capture_output=True, + timeout=30 + ) + + if result.returncode == 0: + startup_time = time.time() - start_time + print(f"Environment startup time: {startup_time:.2f} seconds") + return startup_time < 10 # Should start within 10 seconds + else: + print("Environment startup failed") + return False + + except subprocess.TimeoutExpired: + print("Environment startup timed out") + return False + +def test_memory_usage(): + """Test memory usage of computational environment.""" + process = psutil.Process() + memory_info = process.memory_info() + + memory_mb = memory_info.rss / 1024 / 1024 + print(f"Memory usage: {memory_mb:.2f} MB") + + return memory_mb < 1000 # Should use less than 1GB + +if __name__ == "__main__": + print("Testing computational environment...") + + startup_ok = test_environment_startup() + memory_ok = test_memory_usage() + + if startup_ok and memory_ok: + print("✓ Environment performance tests passed") + else: + print("✗ Environment performance tests failed") +``` + +## 7. Submit and Test in Venue Environment + +Deploy your computational article for live testing: + +### Draft Submission Process +```mermaid +flowchart TD + A[Local Testing Complete] --> B[Submit Draft] + B --> C[Venue Environment Build] + C --> D[Environment Validation] + D --> E[Live Compute Testing] + E --> F{All Tests Pass} + F -->|Yes| G[Ready for Publication] + F -->|No| H[Fix Issues] + H --> I[Resubmit Draft] + I --> D +``` + +### Submission Checklist +```yaml +# submission_checklist.yml +pre_submission: + - "Environment works on mybinder.org" + - "All dependencies are specified" + - "MECA export generates correctly" + - "Notebooks execute without errors" + - "Interactive elements function properly" + - "Performance is acceptable" + +post_submission: + - "Draft builds successfully" + - "Live compute launches correctly" + - "All interactive features work" + - "Session timeout is appropriate" + - "Resource usage is within limits" + - "User experience is smooth" +``` + +### Troubleshooting Common Issues +```python +# troubleshoot.py +import subprocess +import sys + +def check_common_issues(): + """Check for common live compute issues.""" + issues = [] + + # Check Python version + python_version = sys.version_info + if python_version.major != 3 or python_version.minor < 8: + issues.append("Python version should be 3.8+") + + # Check for large files + large_files = [] + for root, dirs, files in os.walk('.'): + for file in files: + filepath = os.path.join(root, file) + if os.path.getsize(filepath) > 100 * 1024 * 1024: # 100MB + large_files.append(filepath) + + if large_files: + issues.append(f"Large files found: {large_files}") + + # Check for missing dependencies + try: + import pandas + import numpy + import matplotlib + except ImportError as e: + issues.append(f"Missing dependency: {e}") + + return issues + +def fix_common_issues(): + """Provide solutions for common issues.""" + solutions = { + "Python version": "Update environment.yml to specify Python 3.9+", + "Large files": "Add large files to .gitignore or use data URLs", + "Missing dependencies": "Add missing packages to requirements.txt", + "Slow startup": "Optimize environment.yml and remove unused packages", + "Memory issues": "Reduce dataset sizes or use data sampling" + } + + return solutions +``` + +## 8. Monitor and Optimize Performance + +Track and improve your live compute performance: + +### Performance Monitoring +```python +# performance_monitor.py +import time +import psutil +import logging + +class LiveComputeMonitor: + def __init__(self): + self.start_time = time.time() + self.session_data = { + 'startup_time': 0, + 'memory_usage': 0, + 'cpu_usage': 0, + 'active_sessions': 0 + } + + def track_startup(self): + """Track environment startup time.""" + startup_time = time.time() - self.start_time + self.session_data['startup_time'] = startup_time + + if startup_time > 30: + logging.warning(f"Slow startup time: {startup_time:.2f}s") + + return startup_time + + def track_resource_usage(self): + """Track resource usage during session.""" + process = psutil.Process() + + memory_mb = process.memory_info().rss / 1024 / 1024 + cpu_percent = process.cpu_percent() + + self.session_data['memory_usage'] = memory_mb + self.session_data['cpu_usage'] = cpu_percent + + return { + 'memory_mb': memory_mb, + 'cpu_percent': cpu_percent + } + + def generate_report(self): + """Generate performance report.""" + return { + 'startup_time': f"{self.session_data['startup_time']:.2f}s", + 'memory_usage': f"{self.session_data['memory_usage']:.2f}MB", + 'cpu_usage': f"{self.session_data['cpu_usage']:.1f}%", + 'recommendations': self.get_recommendations() + } + + def get_recommendations(self): + """Get optimization recommendations.""" + recommendations = [] + + if self.session_data['startup_time'] > 20: + recommendations.append("Consider optimizing environment.yml") + + if self.session_data['memory_usage'] > 500: + recommendations.append("Consider reducing dataset sizes") + + return recommendations +``` + +### Optimization Strategies +```yaml +# optimization_strategies.yml +startup_optimization: + - "Use conda-forge channel for faster package resolution" + - "Specify exact package versions to avoid resolution delays" + - "Remove unused dependencies" + - "Use minimal base images" + +memory_optimization: + - "Sample large datasets for interactive exploration" + - "Use efficient data structures (pandas, numpy)" + - "Implement lazy loading for large files" + - "Cache expensive computations" + +performance_optimization: + - "Pre-compute static visualizations" + - "Use efficient plotting libraries (plotly, altair)" + - "Implement proper error handling" + - "Optimize notebook cell execution order" +``` + +## Next Steps + +- [Learn about Computational Best Practices →](./best-practices.md) +- [Create Computational Articles →](./computational-articles.md) +- [Create Interactive Figures →](./interactive-figures.md) +- [Embed Notebooks in Computational Content →](./embed-notebooks.md) +- [Explore Computational Tiers →](./computational-tiers.md) + +--- + +💡 **Tip:** Always test your environment on mybinder.org first before configuring for Curvenote. This helps identify issues early in the development process. Follow these live compute best practices: + +- **Test early and often**: Validate on mybinder.org before submission +- **Optimize startup time**: Keep environment lean and efficient +- **Monitor performance**: Track resource usage and user experience +- **Document dependencies**: Clearly specify all required packages +- **Handle errors gracefully**: Implement proper error handling in notebooks +- **Plan for scale**: Consider computational tier requirements for your audience diff --git a/editor/reproducible-figures.md b/Computational/reproducible-figures.md similarity index 100% rename from editor/reproducible-figures.md rename to Computational/reproducible-figures.md diff --git a/Getting Started/account-setup.md b/Getting Started/account-setup.md new file mode 100644 index 0000000..dbae798 --- /dev/null +++ b/Getting Started/account-setup.md @@ -0,0 +1,172 @@ +--- +title: Account Setup and Creation +short_title: Account Setup +description: Complete guide to creating and configuring your Curvenote account for optimal workflow and collaboration +--- + +# Account Setup and Creation + +Setting up your Curvenote account properly is the foundation for a successful scientific publishing workflow. This guide will help you create your account, configure your profile, and set up the essential settings for collaboration and publishing. + +## Overview + +By the end of this guide, you will understand how to create a Curvenote account, configure your profile settings, manage teams, and set up your workspace for effective collaboration and publishing. + +## Before You Start + +**Prerequisites:** +- **Email Address**: A valid email address for account creation and verification +- **Web Browser**: Modern web browser with JavaScript enabled + +**Optional Requirements:** +- **ORCID ID**: For academic identity and citation management (supported feature) +- **GitHub Account**: For enhanced collaboration and version control features + +## 1. Creating Your Account + +**Account Creation Process:** +1. **Visit Curvenote**: Go to [curvenote.com](https://curvenote.com) +2. **Sign Up**: Click "Sign Up" or "Create Account" button +3. **Email Verification**: Enter your email address and verify it +4. **Password Setup**: Create a strong, secure password +5. **Account Activation**: Complete the email verification process + +**Account Types:** +- **Free Account**: Basic features for individual users +- **Team Account**: Enhanced collaboration features for groups + +**Security Best Practices:** +- **Strong Password**: Use a unique, complex password +- **Email Verification**: Always verify your email address +- **Regular Updates**: Keep your account information current + +## 2. Profile Configuration + +**Essential Profile Information:** +- **Full Name**: Your complete name as it should appear on publications +- **Professional Title**: Your current role or position +- **Institution**: Your affiliated organization or institution +- **Research Areas**: Your primary fields of study or expertise +- **Bio**: Brief professional description for collaboration + +**Academic Identity:** +- **ORCID Integration**: Link your ORCID ID for academic identity (supported feature) +- **Academic Credentials**: Add relevant degrees and certifications + +**Profile Customization:** +- **Profile Image**: Upload and customize your profile picture +- **Banner Image**: Add a banner image to your profile +- **Public Profile**: Your profile is public and can be reached by anyone with your Curvenote username + +## 3. Team and Collaboration Setup + +**Team Creation:** +- **Create Teams**: Create teams with other Curvenote users for collaboration +- **Team Profiles**: Teams have their own public profiles and can own projects +- **Team Admin**: You become the team admin when you create a team + +**Team Management:** +- **Add Team Members**: Invite users by username to join your team +- **Member Permissions**: Team members can view, create, and edit projects within the team +- **Remove Members**: Remove team members as needed +- **Team Profile Customization**: Customize team profile with images and descriptions + +**Collaboration Features:** +- **Shared Projects**: Work on projects shared with you by other users +- **Public Projects**: Your public projects are shown on your public profile +- **Project Ownership**: Teams can own projects and content + +## 4. Project Organization + +**Project Structure:** +- **Personal Projects**: Organize your individual research projects +- **Collaborative Projects**: Set up shared workspaces for teams +- **Publication Projects**: Structure projects for different publication types + +**Project Management:** +- **Project Creation**: Create new projects for your content +- **Project Sharing**: Share projects with collaborators +- **Project Visibility**: Control which projects are public or private + +**File Organization:** +- **Naming Conventions**: Establish consistent file naming +- **Folder Structure**: Create logical folder hierarchies +- **Version Control**: Track changes in your projects + +## 5. Basic Account Settings + +**Profile Management:** +- **Edit Profile**: Update your public-facing profile information +- **Profile Image**: Add or update your profile image +- **Banner Image**: Customize your profile banner +- **Personal Information**: Update your name, title, institution, and bio + +**Account Information:** +- **Username**: Your Curvenote username for public profile access +- **Email Address**: Manage your email address for account verification +- **Password**: Update your account password as needed + +**Privacy Settings:** +- **Public Profile**: Your profile is public and accessible by username +- **Project Visibility**: Control which projects are publicly visible +- **Team Membership**: Manage your team memberships and roles + +## 6. Getting Started with Content + +**First Steps:** +- **Create Projects**: Start by creating your first project +- **Add Content**: Begin adding articles, notebooks, or other content +- **Explore Features**: Familiarize yourself with the content creation interface +- **Collaborate**: Invite team members to collaborate on projects + +**Content Types:** +- **Articles**: Traditional research articles with text and figures +- **Notebooks**: Computational documents with code and outputs +- **Presentations**: Slide-based content for presentations +- **Books**: Multi-chapter publications + +**Basic Workflow:** +- **Content Creation**: Create and edit your content +- **Collaboration**: Share and collaborate with team members +- **Publication**: Prepare and publish your content +- **Version Control**: Track changes and manage versions + +## 7. CLI Integration (Optional) + +**CLI Setup:** +- **Install CLI**: Install the Curvenote CLI for command-line access +- **Authentication**: Generate API tokens for CLI authentication +- **Basic Commands**: Learn essential CLI commands for project management + +**CLI Features:** +- **Project Management**: Create and manage projects from command line +- **Content Creation**: Create articles and notebooks via CLI +- **Deployment**: Deploy projects to curve.space +- **Configuration**: Manage CLI configuration and settings + +## 8. Next Steps and Support + +**Immediate Next Steps:** +- **Create Your First Project**: Start with a simple project to get familiar +- **Add Team Members**: Invite collaborators to your projects +- **Explore Content Types**: Try different content types and features +- **Learn Advanced Features**: Explore more advanced Curvenote capabilities + +**Support Resources:** +- **Help Documentation**: Access comprehensive help resources +- **Community Forums**: Connect with other Curvenote users +- **Support Tickets**: Submit technical support requests when needed + +**Learning Path:** +- **Basic Content Creation**: Learn to create your first content +- **Collaboration**: Master team collaboration features +- **Advanced Publishing**: Explore advanced publishing options +- **Integration**: Learn about external tool integrations + +## Next Steps + +- [First Steps After Installation →](./first-steps-after-installation.md) +- [Basic Content Creation →](./basic-content-creation.md) +- [Create Your First Project →](./create-project.md) +- [Install the CLI →](./install-cli.md) +- [Learn About Curvenote →](./what-is-curvenote.md) diff --git a/Getting Started/basic-content-creation.md b/Getting Started/basic-content-creation.md new file mode 100644 index 0000000..88d8cd3 --- /dev/null +++ b/Getting Started/basic-content-creation.md @@ -0,0 +1,194 @@ +--- +title: Basic Content Creation +short_title: Content Creation +description: Essential guide to creating your first content in Curvenote, including articles, notebooks, and basic formatting +--- + +# Basic Content Creation + +Creating content in Curvenote is the core of your scientific publishing workflow. This guide will teach you the fundamentals of content creation, from choosing the right format to publishing your work. Whether you're writing articles, creating computational notebooks, or building presentations, this guide covers the essential skills you need. + +## Overview + +By the end of this guide, you will understand how to create different types of content in Curvenote, apply basic formatting, organize your work effectively, and prepare your content for collaboration and publication. + +## Before You Start + +**Prerequisites:** +- **Curvenote Account**: Active Curvenote account with proper setup (see [Account Setup](./account-setup.md)) +- **Basic Installation**: Curvenote installed and configured (see [First Steps](./first-steps-after-installation.md)) +- **Project Created**: At least one project set up for your content + +**Content Planning:** +- **Content Type**: Decide what type of content you want to create +- **Target Audience**: Identify your intended readers +- **Publication Goals**: Understand your publication objectives +- **Collaboration Needs**: Plan for any collaborative work + +## 1. Choosing Your Content Type + +**Article Creation:** +- **Research Articles**: Traditional academic papers with text, figures, and references +- **Review Papers**: Comprehensive reviews of existing literature +- **Case Studies**: Detailed analysis of specific cases or examples +- **Technical Reports**: Technical documentation and reports + +**Notebook Creation:** +- **Computational Notebooks**: Interactive documents with code and outputs +- **Data Analysis**: Notebooks focused on data processing and analysis +- **Tutorial Notebooks**: Step-by-step instructional content +- **Research Notebooks**: Experimental and exploratory work + +**Other Content Types:** +- **Presentations**: Slide-based content for talks and presentations +- **Books**: Multi-chapter publications and textbooks +- **Blog Posts**: Informal content for sharing insights +- **Documentation**: Technical documentation and guides + +**Content Type Selection:** +- **Purpose**: Match content type to your communication goals +- **Audience**: Consider your target audience's needs and preferences +- **Complexity**: Choose appropriate complexity for your content +- **Interactivity**: Decide on the level of interactivity needed + +## 2. Creating Your First Document + +**Document Creation Process:** +1. **Select Template**: Choose an appropriate template for your content type +2. **Set Title**: Create a clear, descriptive title +3. **Add Metadata**: Include author information, abstract, and keywords +4. **Structure Content**: Plan your document structure and sections + +**Template Selection:** +- **Default Templates**: Use built-in templates for common content types +- **Custom Templates**: Create or modify templates for specific needs +- **Template Customization**: Adapt templates to match your style +- **Template Sharing**: Share templates with collaborators + +**Document Setup:** +- **File Naming**: Use clear, descriptive file names +- **Directory Structure**: Organize files in logical directory structures +- **Version Control**: Initialize version control for tracking changes +- **Backup Strategy**: Implement regular backup procedures + +## 3. Basic Text Formatting + +**Text Structure:** +- **Headings**: Use hierarchical heading structure (H1, H2, H3, etc.) +- **Paragraphs**: Organize content into logical paragraphs +- **Lists**: Create ordered and unordered lists for better organization +- **Blockquotes**: Use blockquotes for citations and emphasis + +**Text Styling:** +- **Bold and Italic**: Use emphasis for important terms and concepts +- **Code Formatting**: Format code snippets and technical terms +- **Links**: Add internal and external links for references +- **Special Characters**: Use mathematical symbols and special characters + +**Content Organization:** +- **Introduction**: Start with a clear introduction +- **Main Content**: Organize main content into logical sections +- **Conclusion**: End with a summary or conclusion +- **References**: Include proper citations and references + +## 4. Adding Media and Figures + +**Image Insertion:** +- **Supported Formats**: Use PNG, JPG, SVG, and other common formats +- **Image Optimization**: Optimize images for web and print +- **Alt Text**: Add descriptive alt text for accessibility +- **Image Captions**: Include informative captions for all images + +**Figure Management:** +- **Figure Numbering**: Use consistent figure numbering +- **Cross-references**: Link figures to relevant text sections +- **Figure Placement**: Position figures appropriately in the text +- **Figure Quality**: Ensure high-quality, publication-ready figures + +**Video and Interactive Content:** +- **Video Embedding**: Embed videos from supported platforms +- **Interactive Elements**: Add interactive visualizations and widgets +- **Animation**: Include animated content where appropriate +- **Accessibility**: Ensure all media is accessible to all users + +## 5. Working with Code and Data + +**Code Blocks:** +- **Syntax Highlighting**: Use appropriate syntax highlighting for code +- **Code Organization**: Organize code into logical blocks +- **Comments**: Add clear comments to explain code functionality +- **Code Execution**: Test code blocks to ensure they work correctly + +**Data Integration:** +- **Data Sources**: Connect to various data sources +- **Data Visualization**: Create charts, graphs, and visualizations +- **Data Tables**: Present data in clear, organized tables +- **Data Export**: Export data in appropriate formats + +**Computational Workflows:** +- **Reproducibility**: Ensure computational workflows are reproducible +- **Environment Management**: Manage computational environments +- **Performance Optimization**: Optimize code for performance +- **Error Handling**: Implement proper error handling in code + +## 6. Citation and Reference Management + +**Citation Styles:** +- **Academic Styles**: Use appropriate academic citation styles +- **Automatic Citations**: Leverage automatic citation features +- **Bibliography Management**: Maintain organized bibliographies +- **Citation Updates**: Keep citations current and accurate + +**Reference Integration:** +- **DOI Integration**: Use DOIs for reliable reference linking +- **Reference Validation**: Validate references for accuracy + +**Citation Best Practices:** +- **Consistent Formatting**: Use consistent citation formatting +- **Complete Information**: Include complete reference information +- **Proper Attribution**: Give proper attribution to all sources +- **Citation Ethics**: Follow ethical citation practices + +## 7. Collaboration and Sharing + +**Content Sharing:** +- **Permission Settings**: Set appropriate sharing permissions +- **Collaborator Access**: Grant access to collaborators +- **Version Control**: Use version control for collaborative work +- **Conflict Resolution**: Handle conflicts in collaborative editing + +**Review Process:** +- **Comment System**: Use comments for feedback and discussion +- **Review Workflows**: Implement structured review processes +- **Revision Tracking**: Track changes and revisions +- **Approval Process**: Manage approval workflows + +**Team Collaboration:** +- **Role Assignment**: Assign appropriate roles to team members +- **Project Coordination**: Coordinate work across team members + +## 8. Publishing and Export + +**Publication Preparation:** +- **Content Review**: Review content for accuracy and completeness +- **Format Checking**: Ensure proper formatting and structure +- **Link Validation**: Validate all links and references +- **Final Proofreading**: Conduct final proofreading and editing + +**Export Options:** +- **PDF Export**: Export to PDF for print and distribution +- **HTML Export**: Export to HTML for web publication +- **Word Export**: Export to Word for further editing +- **LaTeX Export**: Export to LaTeX for academic publishing + +**Publication Workflows:** +- **Journal Submission**: Prepare content for journal submission +- **Public Sharing**: Share content publicly through various channels + +## Next Steps + +- [Create Your First Project →](./create-project.md) +- [Install the CLI →](./install-cli.md) +- [Account Setup →](./account-setup.md) +- [First Steps After Installation →](./first-steps-after-installation.md) +- [Learn About Curvenote →](./what-is-curvenote.md) diff --git a/Getting Started/first-steps-after-installation.md b/Getting Started/first-steps-after-installation.md new file mode 100644 index 0000000..e78591a --- /dev/null +++ b/Getting Started/first-steps-after-installation.md @@ -0,0 +1,199 @@ +--- +title: First Steps After Installation +short_title: First Steps +description: Essential guide to getting started with Curvenote immediately after installation, including initial setup and basic workflows +--- + +# First Steps After Installation + +Congratulations on installing Curvenote! This guide will help you take your first steps with the platform, from initial setup to creating your first content. Follow these steps to get up and running quickly and efficiently. + +## Overview + +By the end of this guide, you will understand how to complete the initial setup after installation, verify your installation, explore the interface, and create your first basic content to get familiar with Curvenote's workflow. + +## Before You Start + +**Prerequisites:** +- **Curvenote Installation**: Curvenote CLI or web interface installed and accessible +- **Account Setup**: Curvenote account created and verified (see [Account Setup](./account-setup.md)) +- **Basic System Knowledge**: Familiarity with your operating system and command line (for CLI users) + +**System Requirements:** +- **Terminal/Command Line**: Access to terminal for CLI operations (if using CLI) + +## 1. Verifying Your Installation + +**CLI Installation Verification:** +```bash +# Check Curvenote CLI version +curvenote --version + +# Verify installation location +which curvenote + +# Test basic functionality +curvenote --help +``` + +**Web Interface Verification:** +- **Browser Access**: Navigate to [curvenote.com](https://curvenote.com) +- **Login Test**: Successfully log in to your account +- **Interface Loading**: Verify all interface elements load correctly +- **Feature Access**: Check that basic features are accessible + +**Common Installation Issues:** +- **Path Issues**: Ensure Curvenote is in your system PATH +- **Permission Problems**: Check file permissions and access rights +- **Dependency Issues**: Verify all required dependencies are installed +- **Network Connectivity**: Ensure stable internet connection + +## 2. Initial Configuration + +**Authentication Setup:** +1. **Login**: Authenticate with your Curvenote account +2. **Token Generation**: Generate API tokens if needed for CLI access +3. **Permission Verification**: Ensure you have appropriate access levels + +**Workspace Configuration:** +- **Default Location**: Set your preferred working directory +- **Project Structure**: Create initial project organization +- **Template Selection**: Choose default templates for new content + +**Integration Setup:** +- **GitHub Connection**: Link your GitHub account if desired +- **Notification Preferences**: Configure basic notification settings + +## 3. Exploring the Interface + +**Web Interface Navigation:** +- **Dashboard**: Familiarize yourself with the main dashboard +- **Project Management**: Explore project creation and organization +- **Content Editor**: Understand the content creation interface +- **Settings Panel**: Locate and explore configuration options + +**CLI Interface Exploration:** +```bash +# Explore available commands +curvenote --help + +# List available subcommands +curvenote --help + +# Check your current configuration +curvenote config list +``` + +**Key Interface Elements:** +- **Navigation Menu**: Main navigation and feature access +- **Content Area**: Primary workspace for content creation +- **Toolbar**: Quick access to common actions +- **Status Bar**: System status and progress indicators + +## 4. Creating Your First Project + +**Project Creation Process:** +1. **Choose Project Type**: Select appropriate project template +2. **Set Project Name**: Choose a descriptive project name +3. **Configure Settings**: Set initial project configuration +4. **Initialize Structure**: Create basic project structure + +**Project Templates:** +- **Article Template**: For individual research articles +- **Notebook Template**: For computational notebooks +- **Book Template**: For longer-form publications +- **Custom Template**: For specialized content types + +**Project Organization:** +- **File Structure**: Understand the default file organization +- **Metadata Setup**: Configure project metadata and settings +- **Collaboration Settings**: Set up team access if needed +- **Version Control**: Initialize version control if applicable + +## 5. Basic Content Creation + +**Creating Your First Document:** +1. **Document Type**: Choose between article, notebook, or other formats +2. **Title and Metadata**: Set document title and basic information +3. **Content Structure**: Add initial sections and structure +4. **Save and Version**: Save your work and create initial version + +**Content Types Overview:** +- **Articles**: Traditional research articles with text and figures +- **Notebooks**: Computational documents with code and outputs +- **Presentations**: Slide-based content for presentations +- **Books**: Multi-chapter publications + +**Basic Formatting:** +- **Text Formatting**: Learn basic text formatting options +- **Section Organization**: Create and organize document sections +- **Figure Insertion**: Add images and figures to your content +- **Citation Management**: Add references and citations + +## 6. Understanding the Workflow + +**Content Creation Workflow:** +1. **Planning**: Plan your content structure and organization +2. **Drafting**: Create initial content and structure +3. **Reviewing**: Review and refine your content +4. **Publishing**: Prepare and publish your content + +**Collaboration Workflow:** +- **Sharing**: Share content with collaborators +- **Review Process**: Manage review and feedback cycles +- **Version Control**: Track changes and manage versions +- **Publication**: Coordinate publication process + +**File Management:** +- **Saving**: Regular saving and backup procedures +- **Versioning**: Understanding version control and history +- **Exporting**: Export content in various formats +- **Archiving**: Archive completed or outdated content + +## 7. Testing Basic Features + +**Content Editing Features:** +- **Text Editing**: Test basic text editing capabilities +- **Formatting**: Try different formatting options +- **Media Insertion**: Add images, videos, and other media +- **Code Blocks**: Insert and format code snippets + +**Collaboration Features:** +- **Sharing**: Test content sharing with others +- **Comments**: Add and manage comments +- **Real-time Editing**: Experience real-time collaboration +- **Access Control**: Test permission and access settings + +**Export and Publishing:** +- **Format Export**: Export to different formats (PDF, HTML, etc.) +- **Preview Generation**: Generate previews of your content +- **Publication Process**: Test the publication workflow +- **Integration Testing**: Test external tool integrations + +## 8. Next Steps and Learning Path + +**Immediate Next Steps:** +- **Complete Tutorial**: Work through the basic tutorial +- **Create Sample Content**: Create a sample document or notebook +- **Explore Features**: Try different features and capabilities +- **Join Community**: Connect with other Curvenote users + +**Learning Resources:** +- **Documentation**: Explore comprehensive documentation +- **Video Tutorials**: Watch video tutorials and demonstrations +- **Community Forums**: Join community discussions +- **Support Resources**: Access help and support materials + +**Advanced Features to Explore:** +- **Computational Features**: Explore Jupyter notebook integration +- **Advanced Publishing**: Learn about advanced publishing options +- **API Integration**: Explore programmatic access and automation +- **Customization**: Learn about customization and theming options + +## Next Steps + +- [Basic Content Creation →](./basic-content-creation.md) +- [Create Your First Project →](./create-project.md) +- [Install the CLI →](./install-cli.md) +- [Account Setup →](./account-setup.md) +- [Learn About Curvenote →](./what-is-curvenote.md) diff --git a/adding-content.md b/adding-content.md deleted file mode 100644 index 7fecf92..0000000 --- a/adding-content.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -title: Adding and updating content ---- - -**In this guide you will:** - -- add additional local files to your site, both Markdown `.md` and Jupyter notebooks `ipynb` -- link to a second project on Curvenote, to include it’s content in your website -- pull updated content from Curvenote -- customize the navigation of your site - -```{important} Before you start -This guide assumes that you have completed one of the [Start with a Curvenote project](oxa:Eh6WvY9NT46Ds4lE3OqJ/cMzSX755ZfawTQbU41BV "Start with a Curvenote project") or [Start with a local folder](oxa:Eh6WvY9NT46Ds4lE3OqJ/awl1FKZAY7CpiX7GWWXS "Start with a local folder") tutorials and so have the Curvenote CLI installed (see [Installing Curvenote](oxa:EplL6AlILV3RGEDPzj5U/k4G4ZrOcTIx3szxGNEFb "Installing Curvenote")), Authorized (see [Authorization](oxa:EplL6AlILV3RGEDPzj5U/RzBCtk3yOrXhAVY2z2Bw "Authorization")) and have already started the local development environment at least once. - -``` - -## Add a new project within my website project - -Let’s assume the local project folder has the following structure and content, in this case containing a `content/myblog` subfolder that is linked to a project (also called `myblog` in this example) on Curvenote. - -In this case, `myblog` is my “root” project and the primary project associated with my website. A folder structure like this is typical when you [start with a Curvenote project](oxa:Eh6WvY9NT46Ds4lE3OqJ/cMzSX755ZfawTQbU41BV 'Start with a Curvenote project'). - -```text -_build/* -public/ - logo.svg -content/blog - images/ - DOHMeg040aVXqR51yjBy-v1.jpg - _toc.yml - welcome.md - my-first-post.md - my-first.notebook.ipynb -curvenote.yml -``` - -The corresponding website looks like this: - -```{figure} images/Eh6WvY9NT46Ds4lE3OqJ-r777qnOcE1fKiEHaozw8-v1.png -:name: Kmu0HNj2md -:align: center -:width: 100% - -A [curve.space](https://curve.space) website created from content pulled from a single linked Curvenote project -``` - -🛠️ To add additional projects to your root project, run `curvenote clone`\: - -```shell -> curvenote clone -? Link to Curvenote project: (https://curvenote.com/@templates/curvespace) -``` - -```{important} -**A note on links** - -If the link also contains the name of an article or notebook, this will still work and only the **project** information will be used. You can also use an `oxa` link from the “Copy Link” menu item in Curvenote. - -``` - -🛠️ Next, choose the name of the local sub-folder where content for this project will be placed, the default location is based on the project name and is usually a good choice. - -```shell -? Link to Curvenote project: https://curvenote.com/@stevejpurves/geoscience/phase-and-the-hilbert-transform -Validating link... -🚀 Found "geoscience" (@stevejpurves/geoscience) -? Name of local folder to sync to? (content/geoscience) -``` - -Next, the content for the projects you just cloned will be pulled to your local file system, you can also do this later with `curvenote pull`. - -This command may take some time depending on how much content is in your project, but it will create local copies of all `Articles` (as markdown files `.md`), `Notebooks` (as `.ipynb` files) and linked content such as images and citations. - -```text -Content successfully added 🎉 -``` - -The local folder structure will have been expanded with the additional content and configuration files, to be something like this: - -```text -_build/* -public/ - logo.svg -content/ - blog/ - curvenote.yml - welome.md - ... - geoscience/ - curvenote.yml - paper.md - ... - another-project/ - curvenote.yml - notebook.ipynb - ... -curvenote.yml -``` - -🛠️ Run `curvenote start` to see the site expanded with new content. In the example below, we actually added two new projects, each of which appears as new items in the Navigation on top of the site, and each of which has its own Table of Contents on the left-hand side when navigated to. - -```{figure} images/Eh6WvY9NT46Ds4lE3OqJ-Sn10EXtZHXfzkvaLmXDN-v1.png -:name: iCdLf4niTo -:align: center -:width: 100% - -Example website based on a root project `myblog` that has had content from an additional two projects (`geoscience`, `Computational Finance`) added to it. When a project is “added” it remained linked in the root site configuration which is stored in the `curvenote.yml` file in the root folder. -``` - -### Next Steps - -Now that you have linked projects contributing content to your website, you will need to pull updates from Curvenote check the next section on `pulling updated content`. When projects are added it’s often necessary to tweak the wording and layout of the navigation elements, check the section `Customizing Navigation` for how to achieve that. - -## Pulling updated content - -Pulling updates from Curvenote is achieved using the `curvenote pull` command and will replace all local content with updated content from Curvenote. - -```{note} -**Note** - -Currently, this will remove any local content changes from your folders so is best suited to workflows where any linked projects are modified wholly by authors working on Curvenote. - -Pulling content is therefore a one-way operation. However, in the future `curvenote pull` will allow for fetching updated remote content while preserving any local changes, providing tools for merging and diffs. Watch this space. 🧙 - -``` - -🛠️ In the root of the local folder, run `curvenote pull` - -```shell -curvenote pull -? Pulling content will overwrite all content in folders. Are you sure? (y/N) -``` - -This command will pull content for all projects in one go. To pull updated content for a **single project** add the local content path to the command e.g. `curvenote pull content/myblog` - -```shell -curvenote pull content/myblog -? Pulling will overwrite all content in content/myblog. Are you sure? Yes -Pulling content/myblog from "myblog" (@stevejpurves/myblog) -🚀 Pulled content/myblog in 3.54 s -``` - -## Customizing Navigation - -When projects are added to your site, the `curvenote.yml` file in the root folder is updated to contain the linking information for each project. When projects are added titles are generated based on project names. The `curvenote.yml` file for the example site we’ve shown here is: - -```yaml -version: 1 -site: - title: My Blog - domains: - - stevejpurves.curve.space - logo: public/logo.svg - logoText: My Blog - twitter: stevejpurves - nav: - - title: Blog - url: /myblog - - title: geoscience - url: /geoscience - - title: Computational Finance - url: /computational-finance - projects: - - path: content/myblog - slug: myblog - - path: content/geoscience - slug: geoscience - - path: content/computational-finance - slug: computational-finance - actions: - - title: Learn More - url: https://curvenote.com/docs/web -``` - -🛠️ Update the strings in any of the `title` fields to change the text that appears on your site, in the banner, Navigation and at the top of the Table of Contents for each section. - -```{note} -**Note** - -When modifying the `curvenote.yml` file it may be necessary to halt (CTRL+C) restart the `curvenote start` command to see changes. - -``` - -### Nesting Projects - -When we added projects to our site, they were automatically added as individual items in the Navigation bar. - -```{figure} images/Eh6WvY9NT46Ds4lE3OqJ-xjiptpnTXElB9Mjs7Jvd-v1.png -:name: TfjJYgQ4go -:align: center -:width: 100% -``` - -Alternatively, projects can be grouped together, which can be helpful to manage space on the Navigation bar when there is a lot of linked content and organise similar content together. To do this change the `nav` section in the `curvenote.yml` file from: - -```yaml -nav: - - title: Blog - url: /myblog - - title: geoscience - url: /geoscience - - title: Computational Finance - url: /computational-finance -``` - -to: - -```yaml -nav: - - title: Blog - url: /myblog - - title: Research - children: - - title: geoscience - url: /geoscience - - title: Computational Finance - url: /computational-finance -``` - -This results in a new Navigation layout like this: - -```{figure} images/Eh6WvY9NT46Ds4lE3OqJ-X1raQe1x46aibONnkcSw-v1.gif -:name: bj1YQANn54 -:align: center -:width: 100% -``` - -Find out more about customization in [Navigation & actions](oxa:Eh6WvY9NT46Ds4lE3OqJ/jrOoppptNKmkpA5FmGTU 'Navigation & actions') . - -```{important} -**😎 Cool Example** - -You can see an example of a site with many linked projects that uses this feature to group projects by event, on the [Software Underground Transform Website](https://transform.softwareunderground.org/). - -``` - -## Add new local files to a project - -To add additional files we need to locate the `_toc.yml` file in the folder beside the content and update it. In this case, this is located at `content/blog/_toc.yml`. - -````{important} -**Note** - -If you started by following the [Start with a local folder](oxa:Eh6WvY9NT46Ds4lE3OqJ/awl1FKZAY7CpiX7GWWXS "Start with a local folder") tutorial, your initial layout is probably more like this: - -```text -_build/ -public/ - logo.svg -_toc.yml -welcome.md -my-first-post.md -my-first.notebook.ipynb -curvenote.yml -``` - -So the `_toc.yml` is located at the root of the local folder structure. - -```` - -Opening the `_toc.yml` for this project we see: - -```yaml -# Table of contents -# Learn more at https://jupyterbook.org/customize/toc.html - -format: jb-book -root: welcome -chapters: - - file: my-first-post - - file: my-first-notebook -``` - -To add additional files, or change the ordering of files whether these be `.md` or `ipynb` we can simply extend this list. - -```yaml -# Table of contents -# Learn more at https://jupyterbook.org/customize/toc.html - -format: jb-book -root: welcome -chapters: - - file: my-first-post - - file: my-first-notebook - - file: my-second-post - - file: my-second-notebook -``` - -See to learn how to further structure the table of contents. diff --git a/authoring/adding-content.md b/authoring/adding-content.md new file mode 100644 index 0000000..08b44a5 --- /dev/null +++ b/authoring/adding-content.md @@ -0,0 +1,458 @@ +--- +title: Adding Content to Your Site +short_title: Adding Content +--- + +# Adding Content to Your Site + +## Overview +Learn how to add new content to your Curvenote site, including local files, linked projects, and custom navigation + +This guide shows you how to expand your Curvenote site by adding new content from multiple sources. You'll learn how to add local Markdown files and Jupyter notebooks, link to additional Curvenote projects, pull updated content, and customize your site's navigation structure. + +## Before You Start + +Make sure you have: +- Curvenote CLI installed and authorized +- A local Curvenote project set up +- Access to the Curvenote platform +- Understanding of basic Curvenote concepts +- Git repository (optional, for version control) + +## 1. Understand Content Sources + +Learn about the different ways to add content to your site: + +### Content Source Types + +**Local Files:** +- Markdown (.md) files +- Jupyter notebooks (.ipynb) +- Images and media files +- Configuration files + +**Curvenote Projects:** +- Linked Curvenote projects +- Articles and notebooks from Curvenote +- Shared content from other users +- Template projects + +**External Sources:** +- GitHub repositories +- External websites +- API integrations +- Data sources + +### Project Structure +```mermaid +graph TD + A[Root Project] --> B[Local Content] + A --> C[Linked Projects] + A --> D[External Sources] + + B --> E[Markdown Files] + B --> F[Jupyter Notebooks] + B --> G[Images & Media] + + C --> H[Curvenote Articles] + C --> I[Curvenote Notebooks] + C --> J[Shared Content] + + D --> K[GitHub Repos] + D --> L[External APIs] + D --> M[Data Sources] +``` + +## 2. Add Local Files + +Add new content files directly to your local project: + +### Create New Markdown Files +```bash +# Create a new article +touch content/my-new-article.md + +# Create a new section +mkdir content/new-section +touch content/new-section/index.md +touch content/new-section/article-1.md +touch content/new-section/article-2.md +``` + +### Markdown File Structure + +**Basic Structure:** +- **Frontmatter**: Title, short title, and metadata +- **Main Content**: Article content with sections and subsections +- **References**: Links to related content and external resources + +**Example Elements:** +- Title and introduction sections +- Main content with detailed explanations +- Code blocks and references +- Internal and external links + +### Add Jupyter Notebooks + +**Notebook Structure:** +Create Jupyter notebooks with markdown cells for documentation and code cells for analysis. Include proper metadata and kernel specifications. + +**Example Content:** +- **Markdown Cell**: "# Data Analysis" with descriptive text +- **Code Cell**: Python code for data loading and analysis +- **Metadata**: Kernel specification and notebook format + +### Organize Content Structure + +**Articles:** +- `content/articles/main-article.md` +- `content/articles/supporting-article.md` + +**Notebooks:** +- `content/notebooks/analysis.ipynb` +- `content/notebooks/visualization.ipynb` + +**Data:** +- `content/data/raw/` +- `content/data/processed/` + +**Images:** +- `content/images/figures/` +- `content/images/diagrams/` + +**Assets:** +- `content/assets/documents/` +- `content/assets/code/` + +## 3. Link Curvenote Projects + +Connect additional Curvenote projects to your site: + +### Clone Projects Using CLI +```bash +# Clone a Curvenote project +curvenote clone + +# Interactive prompt will appear: +# ? Link to Curvenote project: (https://curvenote.com/@templates/curvespace) +``` + +### Project Linking Process +```mermaid +flowchart TD + A[Run curvenote clone] --> B[Enter Project URL] + B --> C[Validate Project Link] + C --> D[Choose Local Folder] + D --> E[Download Content] + E --> F[Update Site Structure] + F --> G[Test Local Site] +``` + +### Supported Link Formats + +**Full Project URL:** +`https://curvenote.com/@username/project` + +**Article URL:** +`https://curvenote.com/@username/project/article` + +**Notebook URL:** +`https://curvenote.com/@username/project/notebook` + +**OXA Link:** +`oxa:Eh6WvY9NT46Ds4lE3OqJ/unique-identifier` + +**Example Links:** +- `https://curvenote.com/@stevejpurves/geoscience/phase-and-the-hilbert-transform` +- `oxa:Eh6WvY9NT46Ds4lE3OqJ/cMzSX755ZfawTQbU41BV` +- `https://curvenote.com/@templates/curvespace` + +### Project Configuration + +**Basic Configuration:** +- **Version**: 1 +- **Title**: "Linked Project" +- **Description**: "Additional content from Curvenote" +- **Parent**: "main-project" + +**Content Settings:** +- **Articles**: true +- **Notebooks**: true +- **Images**: true + +**Navigation Settings:** +- **Include in Menu**: true +- **Menu Position**: 2 + +## 4. Manage Content Updates + +Keep your content synchronized and up-to-date: + +### Pull Updated Content +```bash +# Pull updates from all linked projects +curvenote pull + +# Pull updates from specific project +curvenote pull --project project-name + +# Pull with specific options +curvenote pull --force --clean +``` + +### Update Process + +**Content Update Workflow:** +1. Check for updates: `curvenote status` +2. Pull latest content: `curvenote pull` +3. Review changes: `git diff` +4. Test local site: `curvenote start` +5. Commit changes: `git add . && git commit` +6. Deploy updates: `curvenote deploy` + +**Update Monitoring:** +Use `curvenote status` to check if content needs updating. The command will show available updates for linked projects. + + +### Content Synchronization + +**Synchronization Settings:** +- **Auto Pull**: false +- **Pull on Start**: true +- **Conflict Resolution**: manual + +**Excluded Files:** +- `*.tmp` +- `*.log` +- `_build/*` +- `.git/*` + +**Included Content:** +- `*.md` +- `*.ipynb` +- `*.png` +- `*.jpg` +- `*.svg` + +## 5. Customize Navigation + +Organize and structure your site's navigation: + +### Table of Contents Configuration + +**Basic TOC Structure:** +- **Format**: jb-book +- **Root**: index +- **Chapters**: + - `content/blog/welcome` - Welcome + - `content/blog/my-first-post` - My First Post + - `content/geoscience/paper` - Geoscience Paper + - `content/another-project/notebook` - Analysis Notebook + +### Multi-Project Navigation + +**Main Site:** +- Welcome +- About +- Contact + +**Blog Section:** +- Latest Posts +- Categories +- Archive + +**Research Section:** +- Publications +- Data +- Code + +**Projects Section:** +- Current Projects +- Past Projects +- Collaborations + +### Custom Navigation Links + +**Navigation Frontmatter:** +- **Title**: Custom Navigation Example +- **Previous**: `../previous-article` +- **Next**: `../next-article` +- **Parent**: `../section-index` + +[Previous Article →](../previous-article) +[Next Article →](../next-article) +[Back to Section →](../section-index) +## 6. Organize Content Structure + +Consider different approaches to organizing your content for maintainability and clarity: + +### Example Folder Structure + +**Project Root:** +- `_build/` - Build outputs +- `public/` - Static assets (logo.svg, favicon.ico) +- `content/` - Main content directory +- `curvenote.yml` - Main configuration +- `README.md` - Project documentation + +**Content Directory Structure:** +- `index.md` - Home page +- `about.md` - About page +- `blog/` - Blog section + - `_toc.yml` - Table of contents + - `welcome.md` - Welcome post + - `my-first-post.md` - First blog post +- `research/` - Research section + - `_toc.yml` - Table of contents + - `publications/` - Publication files + - `data/` - Research data +- `projects/` - Projects section + - `_toc.yml` - Table of contents + - `project-1/` - Individual project +- `notebooks/` - Jupyter notebooks + - `analysis.ipynb` - Analysis notebook + - `visualization.ipynb` - Visualization notebook + +### Content Metadata + +**Basic Metadata:** +- **Title**: "Article Title" +- **Short Title**: "Short Title" +- **Description**: "Brief description" +- **Authors**: "Author Name" +- **Date**: "2024-01-15" +- **Status**: "published" (draft, published, archived) + +**Tags and Categories:** +- **Tags**: tag1, tag2 +- **Categories**: category1 + +### File Naming Conventions + +**Recommended Patterns:** +- **Markdown Files**: `kebab-case.md` +- **Notebooks**: `descriptive-name.ipynb` +- **Images**: `figure-01.png` +- **Data Files**: `dataset-name.csv` +- **Folders**: `section-name/` + +**Good Examples:** +- `my-first-article.md` +- `data-analysis.ipynb` +- `figure-01-results.png` +- `experiment-data.csv` +- `research-papers/` + +**Avoid:** +- `My First Article.md` (spaces and caps) +- `data_analysis.ipynb` (underscores) +- `figure1.png` (no descriptive name) +- `data.csv` (too generic) +- `Research Papers/` (spaces and caps) + +### Content Organization Best Practices + +For comprehensive guidance on organizing your content effectively, see [Computational Best Practices →](../Computational/best-practices.md) which covers: + +- **Environment Management**: Setting up reproducible computational environments +- **Data Management**: Organizing data files and resources +- **Code Organization**: Structuring code and notebooks for maintainability +- **Documentation Standards**: Creating clear and consistent documentation +- **Version Control**: Managing changes and collaboration + +## 7. Test and Validate Content + +Ensure your content works correctly: + +### Local Testing +```bash +# Start local development server +curvenote start + +# Check for build errors +curvenote build + +# Validate content structure +curvenote check +``` + +### Content Validation + +**Validation Process:** +Use `curvenote check` to validate your content structure and identify potential issues. + +**Validation Checks:** +- **Required Files**: Ensure index.md and curvenote.yml exist +- **Markdown Files**: Verify proper frontmatter in all .md files +- **Notebook Files**: Check for empty or corrupted .ipynb files +- **Internal Links**: Validate that all internal links point to existing files + +### Performance Testing + +**Build Performance:** +Use `curvenote build` to test your site build performance. Monitor build times and optimize if builds take longer than 30 seconds. + +**Performance Monitoring:** +- Check build success/failure status +- Monitor build time duration +- Optimize content if builds are slow +- Review error messages for issues + +## 8. Deploy and Share + +Deploy your updated site and share with others: + +### Deployment Process +```bash +# Deploy to Curvenote +curvenote deploy + +# Deploy with specific options +curvenote deploy --project my-site --public + +# Deploy to custom domain +curvenote deploy --domain mysite.com +``` + +### Deployment Configuration + +**Deployment Settings:** +- **Auto Deploy**: false +- **Deploy on Push**: true +- **Public Access**: true + +**Domains:** +- `mysite.curve.space` +- `custom-domain.com` + +**Settings:** +- **Analytics**: true +- **Search**: true +- **Comments**: false + +### Sharing and Collaboration + +**Sharing Your Site:** +1. **Public Deployment**: Deploy your site publicly for anyone to access +2. **Private Sharing**: Share with specific users or teams +3. **Version Control**: Use Git for collaborative editing +4. **Feedback Collection**: Enable comments and feedback + +**Collaboration Tools:** +- **Git Integration**: Track changes and collaborate via Git +- **Curvenote Teams**: Work with team members on Curvenote +- **Review Process**: Set up review workflows for content +- **Access Control**: Manage who can edit and publish content + +## Next Steps + +- [Learn about Updating Content →](../update-content.md) +- [Customize Site Design →](./site-design/layout-and-theme.md) +- [Configure Navigation →](./site-design/navigation.md) +- [Deploy Your Site →](./tutorial-deploy-project.md) +- [Manage Multiple Projects →](./sites/index.md) + +--- + +💡 **Tip:** Start with a simple content structure and expand gradually. Use descriptive file names and organize content logically from the beginning. + diff --git a/authoring/jupyter-notebooks.md b/authoring/jupyter-notebooks.md index 31878a3..fe7cf0e 100644 --- a/authoring/jupyter-notebooks.md +++ b/authoring/jupyter-notebooks.md @@ -3,9 +3,9 @@ title: Write a Scientific Paper using Jupyter short_title: Write using Jupyter --- -# Writing a Scientific Paper using Jupyter +# Write a Scientific Paper using Jupyter -## Quick Start +## Overview Create publication-quality scientific papers using Jupyter notebooks with Curvenote, combining code execution, interactive outputs, and rich documentation 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. diff --git a/authoring/latex.md b/authoring/latex.md index 04088c2..204dd46 100644 --- a/authoring/latex.md +++ b/authoring/latex.md @@ -1,11 +1,11 @@ --- -title: Writing a Scientific Paper using LaTeX +title: Write a Scientific Paper using LaTeX short_title: Write using LaTeX --- -# Writing a Scientific Paper using LaTeX +# Write a Scientific Paper using LaTeX -## Quick Start +## Overview 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. @@ -500,7 +500,7 @@ project: - [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) +- [Export to LaTeX →](../publishing/export-latex.md) --- diff --git a/authoring/authors.md b/authoring/manage-authors.md similarity index 98% rename from authoring/authors.md rename to authoring/manage-authors.md index 8250045..0be3ae4 100644 --- a/authoring/authors.md +++ b/authoring/manage-authors.md @@ -5,7 +5,7 @@ short_title: Authors # Manage Authors and Contributors -## Quick Start +## Overview 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. @@ -155,7 +155,7 @@ Resolve frequent author management problems: 💡 **Tip:** Use ORCID IDs whenever possible to ensure proper attribution and avoid author name confusion across publications. -⚡ **Important: Author Management Best Practices** +⚡ **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 diff --git a/authoring/markdown-myst-jupyter.md b/authoring/markdown-myst-jupyter.md index 8faccfa..1869cb8 100644 --- a/authoring/markdown-myst-jupyter.md +++ b/authoring/markdown-myst-jupyter.md @@ -5,7 +5,7 @@ short_title: Writing Formats # Writing with Markdown, MyST, or Jupyter -## Quick Start +## Overview 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. @@ -163,8 +163,8 @@ For detailed Jupyter notebook workflows and scientific paper creation, see [Writ **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) +- [Interactive Outputs →](../Computational/interactive-outputs-in-jupyter.md) +- [Reproducible Figures →](../Computational/reproducible-figures.md) --- diff --git a/authoring/myst-markdown.md b/authoring/myst-markdown.md new file mode 100644 index 0000000..b1d7035 --- /dev/null +++ b/authoring/myst-markdown.md @@ -0,0 +1,152 @@ +--- +title: MyST Markdown Guide +short_title: MyST Markdown +description: Complete guide to writing scientific content using MyST Markdown syntax, directives, and advanced features +--- + +# MyST Markdown Guide + +MyST (Markedly Structured Text) is a powerful extension of Markdown designed specifically for scientific and technical documentation. This guide will teach you how to write rich, structured content using MyST Markdown syntax, from basic formatting to advanced features like citations, cross-references, and interactive elements. + +## Overview + +By the end of this guide, you will understand how to write scientific content using MyST Markdown, including basic syntax, advanced directives, citations, cross-references, and interactive elements for creating publication-ready documents. + +## Before You Start + +**Prerequisites:** +- **Basic Markdown Knowledge**: Familiarity with standard Markdown syntax +- **Curvenote Account**: Active Curvenote account for testing and publishing +- **Text Editor**: Any text editor that supports Markdown (VS Code recommended) +- **Basic HTML/CSS**: Understanding of web technologies (helpful but not required) + +**Recommended Tools:** +- **VS Code**: With MyST Markdown extensions +- **Curvenote Editor**: For real-time preview and collaboration +- **Git**: For version control of your content + +## 1. Basic MyST Markdown Syntax + +**Text Formatting:** +MyST Markdown supports all standard Markdown syntax including headings, bold text, italic text, inline code, blockquotes, and lists. Use standard Markdown syntax with hash symbols for headings, asterisks for emphasis, backticks for code, and dashes for lists. + +**Paragraphs and Spacing:** +- **Single line break**: Use two spaces at the end of a line +- **Paragraph break**: Use a blank line between paragraphs +- **Hard line break**: Use backslash at the end of a line + +**Code Blocks:** +Use triple backticks with language specification for code blocks. For example, use three backticks followed by "python" for Python code, or "bash" for shell commands. + +## 2. MyST Directives and Roles + +**Directives Overview:** +MyST directives provide powerful functionality for scientific content. They use a specific syntax with triple colons and options. Directives allow you to create notes, warnings, figures, tables, and other structured content. + +**Basic Directives:** + +**Note Directive:** +Create informational notes using the note directive with triple colons. This displays content in a highlighted note box. + +**Warning Directive:** +Display warnings using the warning directive. This shows content in a warning-styled box. + +**Important Directive:** +Highlight critical information using the important directive. This displays content in a prominent important box. + +**Admonition Directive:** +Create custom admonitions with titles and styling classes. This allows for flexible content highlighting. + +**Content Directives:** + +**Figure Directive:** +Include figures with captions, alignment, and sizing options. Figures can be referenced throughout your document. + +**Table Directive:** +Create structured tables with headers and data. Tables can be given names for cross-referencing. + +## 3. Mathematical Content + +**Inline Math:** +Use single dollar signs for inline mathematical expressions. This allows you to include mathematical notation within your text. + +**Block Math:** +Use double dollar signs for standalone mathematical equations. This creates centered, block-level mathematical content. + +**Aligned Equations:** +Create aligned equation systems using LaTeX alignment environments. This is useful for systems of equations or step-by-step derivations. + +**Math Directives:** +Use math directives for labeled equations that can be referenced throughout your document. + +## 4. Citations and References + +**Basic Citations:** +Cite references using curly braces with the cite role. You can cite single references, multiple references, or include page numbers. + +**Bibliography Setup:** +Configure your document to use a bibliography file. Add the bibliography path to your document frontmatter and include a bibliography section. + +**Reference File:** +Create a BibTeX file with your references. Each reference should have a unique key and include all necessary bibliographic information. + +**Citation Styles:** +MyST supports various citation styles including author-year and numeric formats. You can also include custom text with citations. + +## 5. Cross-References + +**Section References:** +Link to different sections of your document using the ref role. Give sections unique identifiers and reference them throughout your content. + +**Figure References:** +Reference figures using their assigned names. This creates automatic links that update if figure numbers change. + +**Table References:** +Link to tables using their table names. This provides consistent cross-referencing throughout your document. + +**Equation References:** +Reference mathematical equations using their labels. This creates automatic equation numbering and linking. + +## 6. Interactive Elements + +**Code Execution:** +Include executable code cells that can run and display outputs. This is particularly useful for scientific computing and data analysis. + +**Interactive Outputs:** +Create interactive visualizations and plots that readers can interact with. This includes charts, graphs, and other dynamic content. + +**Hide/Show Options:** +Control what parts of code cells are displayed. You can hide code, outputs, or entire cells as needed. + +## 7. Advanced Formatting + +**Custom CSS Classes:** +Apply custom styling to content blocks using CSS classes. This allows for advanced visual customization. + +**Raw HTML:** +Include raw HTML when needed for complex formatting or functionality not available in Markdown. + +**Include External Content:** +Reference and include content from other files. This supports modular document organization. + +**Literal Includes:** +Include code files with syntax highlighting and line number options. + +## 8. Document Structure and Metadata + +**Frontmatter:** +Configure document metadata including title, author, date, and bibliography settings in the document header. + +**Document Options:** +Set various document options for HTML output including MathJax support, table of contents, and navigation depth. + +**Table of Contents:** +Generate automatic table of contents with configurable depth and styling. + +## Next Steps + +- [Writing Markdown, MyST, and Jupyter →](./markdown-myst-jupyter.md) +- [Adding Figures and Images →](./figures-and-images.md) +- [Managing Citations →](./citations.md) +- [Creating Jupyter Notebooks →](./jupyter-notebooks.md) +- [Learn About Curvenote →](../what-is-curvenote.md) diff --git a/authoring/typst.md b/authoring/typst.md index 1e915b5..6f6cb48 100644 --- a/authoring/typst.md +++ b/authoring/typst.md @@ -1,11 +1,11 @@ --- -title: Writing a Scientific Paper using Typst +title: Write a Scientific Paper using Typst short_title: Write using Typst --- -# Writing a Scientific Paper using Typst +# Write a Scientific Paper using Typst -## Quick Start +## Overview 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. @@ -547,7 +547,7 @@ typst compile your_paper.typ --format png - [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) +- [Export to PDF →](../publishing/export-pdf.md) --- diff --git a/authoring/version-history.md b/authoring/version-history.md index 35e3734..eb34306 100644 --- a/authoring/version-history.md +++ b/authoring/version-history.md @@ -94,7 +94,7 @@ Make sure you have: - [Reuse Content Blocks →](./reuse-blocks.md) - [Organize Your Content →](./organize-content.md) -- [Export Your Work →](../editor/export-pdf.md) +- [Export Your Work →](../publishing/export-pdf.md) --- diff --git a/computational-articles.md b/computational-articles.md deleted file mode 100644 index 91e9b85..0000000 --- a/computational-articles.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Computational Articles -short_title: Overview ---- - -We have identified two main patterns that take advantage of Curvenote's computational capabilities: **Computational Articles** and **Computational Reports**. - -Computational Articles -: Structured around a core manuscript with attached supporting materials, **computational articles** focus on providing **in-context interactive figures** and notebooks with a strong narrative flow. Interactive figures can be executed independently, and notebooks are integrated into the main content. A separate JupyterLab environment can be launched by the reader, allowing them to explore the content fully and encourage re-use and further experimentation. -: Examples: [pyUserCalc](https://agu.curve.space/articles/NN0002) - -Computational Reports & Tutorials -: Computational reports include the same interactive features as articles, they are structured more like a "book"—presenting a collection of notebooks within a broader narrative. These reports emphasize comprehensive documentation and exploration of the computational environment. Readers can launch a **JupyterLab instance** to interact with the notebooks or, optionally, execute the notebooks in place within the report. -: Example: [Tilt-Corrected BF-STEM](https://www.elementalmicroscopy.com/articles/EM000002) - -In both cases, it's important to carefully consider the **computational environment** for your article or report. Whether you're working in Python, Julia, or R, best practices for **dependency management** and **reproducibility** are essential. diff --git a/computational-tiers.md b/computational-tiers.md deleted file mode 100644 index 172206b..0000000 --- a/computational-tiers.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Computational Tiers ---- - -Curvenote provides a range of **compute services** to support the interactive and computational aspects of your articles. These services are delivered through a private {term}`BinderHub`, ensuring that all computational environments are isolated and securely managed. We also **store the images** used in these environments to ensure that they can be accessed quickly, minimizing the time it takes for readers to start interacting with your article's computational components. - -Each **tier** is designed to scale according to your needs, allowing you to select the appropriate level of compute resources depending on the expected **traffic** and **complexity** of your article's interactive features. - -It’s important to note that the **initial load** of an article does **not trigger compute resources** to be used. Compute is only engaged when a reader opts to interact with the figures or execute the computational steps independently, ensuring optimal use of resources. - -### Compute Tier Descriptions - -```{list-table} Curvenote offers three main computational tiers. -:header-rows: 1 -:label: tab:computational-tiers - -* - Name - - Description -* - **Tier 1** \ - Shared compute - - The entry-level compute service, private to Curvenote customers, is provided as part of our infrastructure for **lab groups** and small **independent journals/collections**. It includes access to **shared end-user servers**, which are ideal for lightweight interactive visualizations and smaller datasets. -* - **Tier 2** \ - Dedicated single instance - - In this tier, we provide a **dedicated single-instance host** for a journal or project. This setup ensures improved **availability** of compute resources, allowing more consistent performance when readers request servers for interactive tasks. This service can be **scaled** based on the journal’s specific needs and traffic demands. -* - **Tier 3** \ - Dedicated cluster-based hub - - For larger projects or journals that require substantial compute resources, we offer a **dedicated cluster-based hub**. This option provides enhanced **availability and reliability**, with more efficient use of compute resources as traffic or computational requirements increase. This is the most scalable option and becomes cost-effective at higher compute usage levels. -``` - -### Choosing the Right Tier - -The tier you select should be based on the **scale** of your project and the **interaction complexity** within your articles. If your readers are primarily interacting with lightweight visualizations, the **shared compute** tier may be sufficient. For larger journals or projects that expect high levels of interaction and require more **consistent availability**, a **dedicated instance** or **cluster-based hub** will provide the necessary performance and reliability. - -Where computation is required it is necessary to connect to a compute service to start a service for the reader, on demand. This scales based on **concurrent users**, which is defined as a user who is actively connected to our servers within the same 45 minute time period. - -### Key Features Across All Tiers - -- **Private BinderHub**: All compute services are managed through a secure, private BinderHub, ensuring that each journal or article’s resources are isolated and managed independently. -- **Stored Images for Speed**: We store computational images, ensuring **fast access** for readers when they begin interacting with articles. -- **Scale as Needed**: Each tier is scalable based on consultation, so you can tailor the compute environment to the specific needs of your project. - -### When Compute Resources Are Triggered - -It is important to note that Curvenote articles remain fully readable without being connected to a compute service, in some cases these can also include interactive graphs and data without the need for connected computation although this is content dependent. Compute resources are only engaged when a reader chooses to interact beyond the static content of an article. This may include: - -- Exploring **interactive figures** and widgets. -- **Executing code** or rerunning analyses embedded in a Jupyter Notebook. -- Engaging with datasets or models in real-time. - -This ensures that the resources are only used when needed, optimizing the use of compute power while maintaining an efficient, reader-friendly experience. - -### Consultation and Setup - -Setting up the right compute environment for your journal or project is done in **consultation** with Curvenote. Our team will help assess your expected traffic, computational needs, and any specific requirements your articles may have. This ensures that you receive the right tier and scaling options from the start, providing both reliability and cost-efficiency. - -For more information or to get started with your compute tier, please [contact us](https://curvenote.com/demo). diff --git a/deploying-myst-from-github.md b/deploying-myst-from-github.md deleted file mode 100644 index 2600090..0000000 --- a/deploying-myst-from-github.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Deploying to curve.space from GitHub -short_title: Deploying from GitHub -description: >- - Curvenote provides a deployment action in the GitHub Marketplace, allowing you - to easily add automated deployment to your repository. -subject: How To -venue: MyST Websites ---- - -In this guide, we’ll take you through the steps of using GitHub to version your website and collaborate with others, while also using GitHub Actions to deploy your website. - -**In this guide you will learn about:** - -- What to commit to your repository on GitHub -- Adding a CI workflow, using the Curvenote Deploy action from the GitHub action marketplace -- How to check the status of your deployment -- Good development practices, to avoid deploying draft content to your site - -```{important} -**Before you Start** - -This guide assumes that (1) you already have an initialized curvenote project in a local folder, and (2) that this local folder is also a GitHub repository. - -1. to initialize your curvenote project see [Start with a local folder](./tutorial-deploy-local.md) -2. to initialize your git repository see GitHub’s guides on [git init](https://github.com/git-guides/git-init), [creating a repo](https://docs.github.com/en/get-started/quickstart/create-a-repo) and [managing remotes](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories) - -``` - -## What to commit to git - -After working with a curvenote website locally, a number of files and folders will be created within your local folder alongside your content. Some of these should be committed to `git`, while others should be ignored. - -- add `curvenote.yml` files to `git` - there will be at least one file at the root of your repo and potentially others in content subfolders for more complex configurations -- ignore the `_build/` folder by adding it to your `.gitignore` - this is only used for a caching local build assets when using `curvenote start` - -## Deploying from CI using GitHub Actions - -Curvenote provides a deployment action in the GitHub Marketplace, allowing you to easily add automated deployment to your repository. - -```{figure} images/Eh6WvY9NT46Ds4lE3OqJ-xAQ7dOyRVASM2PDWJBDg-v1.png -:name: QF7z0XV7wO -:align: center -:width: 80% - -Curvenote Deploy action on the [GitHub Marketplace](https://github.com/marketplace/actions/curvenote-deploy) -``` - -### Add a new GitHub workflow - -In your repository create a new file on the following path `.github/wofklows/deploy.yml`. And then copy the following `yml` into that file. - -```yaml -name: Curvenote Deploy -on: - push: - branches: - - main -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - name: Deploy to curve.space - uses: curvenote/action-deploy@v1 - env: - CURVENOTE_TOKEN: ${{ secrets.CURVENOTE_TOKEN }} -``` - -This will run on any push to the `main` branch and requires an API token to work. - -### Generate a new API token - -It is good practice to use separate API tokens for your different environments, making it easy to remove one of needed whilst not affecting others. Generate a new API Token as described in [Authentication](./authentication.md). - -On GitHub, navigate to your repository and follow [this guide from GitHub](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) to add a new “Repository Secret”. This secret should be named `CURVENOTE_TOKEN` and the value set to the API token string. - -### Commit, push and test - -If you have not already, commit your changes and push to `main`. The github action will run automatically and will complete with success ✅ if the content was built and site deployed correctly. - -```{figure} images/Eh6WvY9NT46Ds4lE3OqJ-1phwIyExAdZmNQk0O8XM-v1.png -:name: AzfNhoF8ot -:align: center -:width: 100% - -You can see the status of your deployments in the Actions tab on your repository in GitHub. On any failure you will need to click on the action and check the logs to debug the issue. -``` - -### Pulling content from linked projects - -If your website project, includes other linked projects on [curvenote.com](Curvenote.com) then you may want to automatically include the latest changes from those projects on deployment. - -To do so modify the `.github/workflows/deploy.yml` file to include the following option: - -```yaml -steps: - - uses: actions/curvenote-deploy@v1 - with: - pull: true -``` - -## Development practices - -In many cases, you’ll want to be able to push working changes to git without triggering a deployment of your site. There are a few different ways you can achieve this. - -### Develop on branches - -Most suitable for single developers or small teams, simply create a branch for any changeset you are making and review this via a Pull Request (PR) into the `main` branch. Only merge your PR when you are ready to deploy your changes. - -### Create a `dev` branch - -Most suitable for teams, creating a long lived `dev` or `develop` branch allows multiple developers to easily collaborate and work on multiple feature branches, while still being able to integrate those changes into `dev` regularly. When a changeset is ready to deploy `dev` should be merged into `main`, usually via a PR for review. To learn more about development practices like this [read about gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). - -### Deploy from a different branch - -The last two scenarios both deploy from main which is convenient and requires no change to the default workflow setup provided above. We recommend deploying from `main` and using one of those strategies. However, if you do want to deploy from a separate `release` branch, simply modify the `.github/workflows/deploy.yml` and replace `main` with the new branch name e.g. `release`. - -```yaml -on: - push: - branches: - - release -``` diff --git a/github-actions.md b/github-actions.md deleted file mode 100644 index 745dbfc..0000000 --- a/github-actions.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: GitHub Actions for Publishing -github: https://github.com/curvenote/actions ---- - -Curvenote provides GitHub actions to connect your GitHub repository to a Curvenote Site and run your [editorial workflow from pull requests](./submissions-using-github.md). The actions are available on GitHub ([curvenote/actions](https://github.com/curvenote/actions)). - -:::{tip} Prerequisites -:class: dropdown -Site -: You must have an active Curvenote site to use this action. To publish to our free hosting service, see [](./tutorial-deploy-local.md). - -Access -: A Curvenote API token is required. See [secret management](#secret-management) below. -::: - -## Example Workflow - -```{code-block} yaml -:filename: .github/workflows/publish.yml -:caption: A repository that runs actions on pull requests for a folder of submissions. -name: curvenote -on: - pull_request: - branches: ['main'] -permissions: - contents: read - pull-requests: write -jobs: - publish: - uses: curvenote/actions/.github/workflows/publish.yml@v1 - with: - monorepo: true - id-pattern-regex: '^-(?:[a-zA-Z0-9-_]{3,15})$' - enforce-single-folder: true - preview-label: paper - submit-label: true - venue: '' - collection: '' - kind: '' - path: papers/* - secrets: - CURVENOTE: ${{ secrets.CURVENOTE_TOKEN }} - GITHUB: ${{ secrets.GITHUB_TOKEN }} -``` - -When set up for a `monorepo` (i.e. there is more than one submission in the GitHub repository), then the publish job will create an action workflow with 4 steps: (1) a **strategy**, which determines what actions should be run; (2) a **preview** which will post the submission to Curvenote as a draft or part of an ongoing submission; (3) a local **check** job that validates each submission against the venues criteria; and (4) a summary job that posts information back to the GitHub pull request. - -:::{figure} ./images/github-action-overview.png -::: - -### Action Options - -Curvenote’s integrated previews are highly customizable. You can configure your workflow to generate different types of previews based on your project's needs: - -- **Branch Previews**: Every commit on a branch generates a unique preview, allowing for easy tracking of changes in real-time. -- **Pull Request**: When a pull request is opened, a **draft** preview can be generated. This draft can be reviewed, commented on, and iterated upon without affecting the main branch. - -By configuring the action, you can control the scope and depth of previews, ensuring that only necessary builds are triggered, reducing build times while still providing instant feedback on content changes. - -`monorepo` (boolean) -: When `true` indicates that this repository contains multiple projects that should be published. For example, if you have multiple articles, or tutorials that should be previewed and submitted when there are changes in the repository. - -`id-pattern-regex` (string - regex) -: A regular expression that all IDs must follow, by default this matches a UUID. - - This can be used to enforce that all project IDs follow a specific pattern, such as, - the conference name + year. - - The ID must also satisfy alphanumeric characters, dashes, and underscores. - -`enforce-single-folder` (boolean) -: When `true`, an error will be raised if a pull-request is touching multiple -different folders. This can either be `true` or a label string. -Multiple labels can be added with comma-separated values. - - If labels are used to control this property, the pull request will only fail in - PRs with these labels. - - This can be used in conjunction with the `preview-label`, for example, if they - are both `paper` then the PRs with those labels will be required to only make changes - in a single folder and will not be previewed if that condition fails. - However, you can add additional preview labels, e.g. `all-papers`, which will build - previews for all papers, as the single folder condition is not enforced for that label. - -`preview-label` (string) -: A pull-request label that indicates the preview and checks should be run. -Multiple labels can be added with comma-separated values. - - If no label is supplied, the preview will run on all PRs. - -`submit-label` (string) -: A pull-request label that indicates the branch should be turned into a submission. -This will notify all curators of the Curvenote site. - - The submission identifiers will be written directly to the repository in a commit, - and the submission will be available to be merged on the Curvenote platform. - - A submission will not happen unless both the `enforce-single-folder` and `preview-label` - conditions are satisfied. - -`venue` (string) -: The site or venue that this project is being submitted to. - -`collection` (string) -: The venue's collection that this project is being submitted to. - -`kind` (string) -: The kind of the submission, that must be a kind included in the `collection` being submitted to. - -`path` (string - glob pattern) -: The root directory path(s) where the Curvenote CLI will be invoked. If `multiple` paths are being used, separate the `path` string with ','. The paths can also be glob-like patterns (but only one `*`), for example: - - ```yaml - path: my/project - path: my/paper, my/poster - path: papers/*, posters/* - ``` - - The default path is the root of the repository. - -`ref` (string) -: The branch, tag or SHA to checkout. When checking out the repository that triggered a workflow, this defaults to the reference or SHA for that event. - -(secret-management)= - -### Secret Management - -A Curvenote API token is required. This can be added as a secret within your [GitHub Repository or Environment](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). - -An API Token can be generated for any user account at [curvenote.com](https://curvenote.com/profile?settings=true&tab=profile-api&subtab=general), the user account used must be on the Team a associated with your site and have sufficient rights. diff --git a/integrations/github.md b/integrations/github.md new file mode 100644 index 0000000..594fea5 --- /dev/null +++ b/integrations/github.md @@ -0,0 +1,290 @@ +--- +title: GitHub Integration +short_title: GitHub +description: Complete guide to integrating Curvenote with GitHub for version control, collaboration, and automated deployment +--- + +# GitHub Integration + +Curvenote provides comprehensive GitHub integration for version control, collaboration, and automated deployment of your scientific content. + +## Overview + +GitHub integration enables you to: +- **Version control** your Curvenote projects with Git +- **Collaborate** with others through pull requests and reviews +- **Automate deployment** using GitHub Actions +- **Host computational environments** for reproducible research +- **Manage editorial workflows** from submission to publication + +## Quick Reference + +| Feature | Description | Documentation | +|---------|-------------|---------------| +| **GitHub Actions** | Automated deployment and previews | [GitHub Actions →](../github-actions.md) | +| **Deployment** | Deploy to curve.space from GitHub | [Deploying from GitHub →](../deploying-myst-from-github.md) | +| **Editorial Workflow** | Pull request-based publishing | [Submissions using GitHub →](../submissions-using-github.md) | +| **CLI Integration** | Command-line GitHub workflows | [CLI Workflows →](../cli/workflows.md) | +| **Content Linking** | Link to GitHub repositories | [Link Data & Code →](../authoring/link-data-code.md) | +| **Computational** | Host environments on GitHub | [Live Compute →](../Computational/live-compute.md) | + +## Core Integration Features + +### 1. Version Control & Collaboration + +**Git Repository Setup:** +```bash +# Initialize Git repository +git init + +# Add Curvenote project files +git add . + +# Commit changes +git commit -m "Initial Curvenote project" + +# Connect to GitHub +git remote add origin https://github.com/username/repo-name.git +git push -u origin main +``` + +**Collaborative Workflow:** +- **Fork repositories** for independent work +- **Create branches** for feature development +- **Submit pull requests** for review and merging +- **Use GitHub Issues** for tracking tasks and bugs + +### 2. GitHub Actions for Automation + +**Deployment Workflow:** +```yaml +# .github/workflows/deploy.yml +name: Deploy to Curvenote +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: curvenote/actions/.github/workflows/publish.yml@v1 + with: + token: ${{ secrets.CURVENOTE_TOKEN }} + github: ${{ secrets.GITHUB_TOKEN }} +``` + +**Available Actions:** +- **`curvenote/actions/.github/workflows/publish.yml`** - Deploy and preview +- **`curvenote/actions/.github/workflows/check.yml`** - Validation and testing +- **`curvenote/actions/.github/workflows/export.yml`** - Export to various formats + +### 3. Editorial Workflow Integration + +**Pull Request Process:** +1. **Fork repository** to your GitHub account +2. **Create feature branch** for your article +3. **Submit pull request** with your changes +4. **Automated checks** run validation and previews +5. **Review process** with inline comments and suggestions +6. **Merge and publish** when approved + +**Automated Features:** +- **Preview generation** - Live preview accessible via GitHub comment +- **Validation checks** - Format, links, and content validation +- **Status updates** - Real-time feedback on pull request status +- **Integration comments** - Automatic posting of build results + +### 4. Content Linking + +**Link to GitHub Repositories:** +```markdown +[GitHub Repository](https://github.com/username/project-name) + +{download}`Download Code ` + +{code-cell} +--- +tags: [hide-input] +--- +!git clone https://github.com/username/project-name.git +``` + +**Supported Link Types:** +- **Repository links** - Direct links to GitHub repos +- **File links** - Links to specific files or notebooks +- **Release links** - Links to tagged releases +- **Issue links** - Links to GitHub issues and discussions + +### 5. Computational Environment Hosting + +**BinderHub Integration:** +```yaml +# environment.yml for GitHub-hosted environments +name: computational-research +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - pandas>=1.5.0 + - numpy>=1.21.0 + - matplotlib>=3.5.0 + - jupyterlab>=3.5.0 + - pip + - pip: + - jupyterlab-myst>=0.2.0 + - myst-nb>=0.17.0 +``` + +**Environment Setup:** +- **Public repositories** - Automatically available on mybinder.org +- **Private repositories** - Use Curvenote's private BinderHub +- **Environment files** - `environment.yml`, `requirements.txt`, `apt.txt` +- **Repository structure** - Standard Jupyter project layout + +## Configuration + +### Repository Setup + +**Required Files:** +``` +your-repo/ +├── .github/ +│ └── workflows/ +│ └── deploy.yml +├── curvenote.yml +├── environment.yml (optional) +├── requirements.txt (optional) +└── README.md +``` + +**GitHub Secrets:** +- **`CURVENOTE_TOKEN`** - Curvenote API token for deployment +- **`GITHUB_TOKEN`** - GitHub token for repository access + +### Curvenote Configuration + +**`curvenote.yml` with GitHub settings:** +```yaml +version: 1 +project: + title: "Your Project" + description: "GitHub-integrated Curvenote project" + + # GitHub integration settings + github: + repository: "username/repo-name" + branch: "main" + workflow: "deploy.yml" + + # Deployment settings + deployment: + platform: "curve.space" + domain: "your-site.curve.space" + auto_deploy: true +``` + +## Best Practices + +### Repository Organization + +**Recommended Structure:** +``` +project/ +├── articles/ # Individual articles +├── notebooks/ # Jupyter notebooks +├── data/ # Data files (use Git LFS for large files) +├── environments/ # Environment configurations +├── docs/ # Documentation +└── .github/ # GitHub workflows and templates +``` + +**File Management:** +- **Use Git LFS** for large data files (>100MB) +- **Keep environments reproducible** with exact version pins +- **Document setup** in README files +- **Use meaningful commit messages** for better collaboration + +### Security Considerations + +**Token Management:** +- **Never commit tokens** to repositories +- **Use GitHub Secrets** for sensitive data +- **Rotate tokens regularly** for security +- **Limit token permissions** to minimum required + +**Repository Security:** +- **Enable branch protection** for main branches +- **Require pull request reviews** before merging +- **Use signed commits** for verification +- **Regular security updates** for dependencies + +### Performance Optimization + +**Build Optimization:** +- **Cache dependencies** in GitHub Actions +- **Use shallow clones** for faster checkouts +- **Optimize image sizes** for computational environments +- **Parallel workflows** for independent tasks + +**Repository Optimization:** +- **Clean Git history** with regular maintenance +- **Archive old branches** to reduce repository size +- **Use .gitignore** to exclude unnecessary files +- **Monitor repository size** and performance + +## Troubleshooting + +### Common Issues + +**Deployment Failures:** +```bash +# Check GitHub Actions logs +# Verify token permissions +# Ensure repository access + +# Common solutions: +# 1. Regenerate CURVENOTE_TOKEN +# 2. Check branch protection rules +# 3. Verify workflow file syntax +# 4. Ensure all required files exist +``` + +**Authentication Issues:** +- **Token expired** - Generate new token in Curvenote settings +- **Insufficient permissions** - Check token scope and repository access +- **Repository not found** - Verify repository URL and access rights + +**Build Failures:** +- **Missing dependencies** - Check environment files +- **Syntax errors** - Validate YAML and markdown files +- **Resource limits** - Optimize computational requirements + +### Getting Help + +**Support Resources:** +- **GitHub Actions logs** - Detailed error information +- **Curvenote documentation** - Comprehensive guides +- **GitHub community** - Community support and examples +- **Curvenote support** - Direct technical assistance + +**Debugging Steps:** +1. **Check GitHub Actions** for detailed error logs +2. **Verify configuration** files and settings +3. **Test locally** with Curvenote CLI +4. **Review recent changes** that might have caused issues +5. **Check dependencies** and environment compatibility + +## Next Steps + +- [Set up GitHub Actions →](../github-actions.md) +- [Deploy from GitHub →](../deploying-myst-from-github.md) +- [Use GitHub for submissions →](../submissions-using-github.md) +- [Configure CLI workflows →](../cli/workflows.md) +- [Link to GitHub repositories →](../authoring/link-data-code.md) +- [Host computational environments →](../Computational/live-compute.md) +- [Learn about best practices →](../Computational/best-practices.md) diff --git a/live-compute.md b/live-compute.md deleted file mode 100644 index 4f4f6dc..0000000 --- a/live-compute.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Live Compute ---- - -### BinderHub and REES - -To continue you should be familiar with the public My Binder service, hosted at https://mybinder.org, if not please [read the docs](https://mybinder.readthedocs.io/en/latest/) and try using it. Your Computational Article or Report will be using a version of Binder ({term}`BinderHub`) behind the scenes, however, it is private and hosted by Curvenote and is therefore much faster to start as we cache our users images (see [](./computational-tiers.md)). - -BinderHub supports a range of different configuration files and options that are designed to help you get a collection of code and notebooks running in a reproducible manner. The specification for that is called REES and you can read more about [the different configuration files here](https://repo2docker.readthedocs.io/en/latest/config_files.html). - -You'll see that many of these are just the standard dependency management files (like `requirements.txt` or `environment.yml`) that you will be used to from working in a python or R environment. - -#### Add MyST Markdown support to Jupyter Lab - -To include support for MyST Markdown in you can simply add `jupyterlab-myst` as a dependency in your `requirements.txt` or `environment.yml` files. This will mean that any MyST markdown syntax in your `.md` files or notebooks will be properly rendered. - -### Running on mybinder.org - -A good initial test of your computational environment setup is to ensure that your code and notebooks work on mybinder.org - that should be your first step and probably means getting your work into a public repo on GitHub. - -```{tip} -If you are not able to use the public mybinder.org service, perhaps because you cannot make your work public, then you can still proceed with the following steps and use Curvenote's [draft submissions](./authoring/submitting-your-work.md) for testing. -``` - -### Configuration via Frontmatter - -Beyond running on the mybinder.org service, your environment needs a little more configuration before it is ready for use as an Article or Report. This is a matter of including additional frontmatter fields in your `curvenote.yml` or `myst.yml`. - -Here is an example: - -```yaml -version: 1 -project: - ... - jupyter: true - exports: - - format: meca - requirements: - - requirements.txt - - apt.txt - resources: - - src/**/* - - example.csv - - model.pkl -``` - -`jupyter` -: (boolean) Enables or disables computation - -`exports[format:meca]` -: ([list:exports](https://mystmd.org/guide/frontmatter#frontmatter-exports)) The `exports` list should include a `meca` export. You may have other exports listed, like `pdf`, that is fine too. The MECA archive is used to collect and store the entire reproducible environment behind your article or report - -`requirements` -: (list:string) This is a list of the REES compatible files that should be included in your submission - -`resources` -: This is a list of files, folders, or glob patterns, that should be included in your submission. Note that all files listed in your `_toc.yml` will be automatically included. - -### Testing on my computer - -To confirm that your submission builds run: - -```bash -curvenote export meca -``` - -You will be able to see a `*.zip` file in the `_build/exports` folder, confirm that this zip file contains your expected environment. - -### Testing in the Venue's environment - -Next you can test your submission in the Venue's environment by submitting a _Draft_. To start working with draft submissions go to the [Submitting you Work](./authoring/submitting-your-work.md) guide. diff --git a/myst.yml b/myst.yml index 0704109..3968990 100644 --- a/myst.yml +++ b/myst.yml @@ -40,13 +40,7 @@ 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 @@ -55,12 +49,6 @@ project: - file: getting-started/create-article-cli.md - file: getting-started/publish-article.md - file: getting-started/create-a-site.md - - title: Design & Customize Your Site - children: - - file: site-design/layout-and-theme.md - - file: site-design/planning.md - - file: site-design/custom-domains.md - - file: site-design/navigation.md - title: Authoring Content children: - file: authoring/citations.md @@ -71,19 +59,11 @@ project: - file: authoring/reuse-blocks.md - file: authoring/version-history.md - file: authoring/writing-markdown-myst-jupyter.md - - - title: Computational articles - children: - - file: computational-articles.md - - file: live-compute.md - - file: computational-tiers.md - - file: large-scale-data.md - - title: Automation - children: - - file: submissions-using-github.md - - file: github-actions.md - - file: integrated-previews.md - - file: deploying-myst-from-github.md + - file: authoring/jupyter-notebooks.md + - file: authoring/latex.md + - file: authoring/typst.md + - file: authoring/figures-and-images.md + - file: authoring/myst-markdown.md - title: Publishing children: - file: publishing/editorial-process.md @@ -93,110 +73,53 @@ project: - file: publishing/graceful-degradation.md - file: publishing/kinds.md - file: publishing/collections.md - # - title: Integrations - # children: - # - file: integrations/crossref.md - # - file: integrations/github.md - # - file: integrations/orcid.md - # - file: integrations/openalex.md - # - file: integrations/zenodo.md - # - file: integrations/figshare.md - # - file: integrations/ror.md - # - file: integrations/rrid.md - # - file: integrations/wikipedia.md - # - file: integrations/funder-registry.md - # - file: integrations/biorxiv.md - # - file: integrations/arxiv.md - # - file: integrations/typst.md - # - file: integrations/jats.md - # - file: integrations/meca.md - # - file: integrations/google-scholar.md - # - file: integrations/doi.md - # - file: integrations/prereview.md - # - file: integrations/ithenticate.md - # - file: integrations/pubmed-central.md - # - file: integrations/credit.md - # - file: integrations/sphinx.md - # - file: integrations/myst.md - # - file: integrations/jupyter.md - # - file: integrations/youtube.md - # - file: integrations/google-drive.md - # - file: integrations/proofig.md - # - file: integrations/binderhub.md - # - title: Tools - # class: section - # children: - - title: Curvenote CLI + - file: publishing/export-pdf.md + - file: publishing/export-latex.md + - file: publishing/export-pdf-typst.md + - file: submissions-using-github.md + - file: github-actions.md + - file: deploying-myst-from-github.md + - file: integrated-previews.md + - title: Computational + children: + - file: computational-articles.md + - file: live-compute.md + - file: computational-tiers.md + - file: large-scale-data.md + - file: Computational/best-practices.md + - file: Computational/embed-notebooks.md + - file: Computational/interactive-figures.md + - file: Computational/interactive-outputs-in-jupyter.md + - file: Computational/reproducible-figures.md + - file: Computational/computational-articles.md + - file: Computational/computational-tiers.md + - file: Computational/live-compute.md + - title: Site Design + children: + - file: site-design/layout-and-theme.md + - file: site-design/planning.md + - file: site-design/custom-domains.md + - file: site-design/navigation.md + - file: adding-content.md + - file: update-content.md + - title: Command Line Tools children: - file: cli/index.md - file: cli/installing.md - file: cli/installing-prerequisites.md - file: cli/authentication.md - file: cli/commands.md - - title: Curvenote Editor - children: - - title: Account - children: - - file: editor/curvenote-profile.md - - file: editor/curvenote-teams.md - - file: editor/curvenote-projects.md - - file: editor/collaboration.md - - title: Writing - children: - - file: editor/editing.md - - file: editor/command-menu.md - - file: editor/markdown-accelerators.md - - file: editor/editing-toolbar.md - - file: editor/authors.md - - title: Organization - children: - - file: editor/articles.md - - file: editor/blocks.md - - file: editor/navigation.md - - title: Content - children: - - file: editor/formatting-and-style.md - - file: editor/figures-and-images.md - - file: editor/math-and-equations.md - - file: editor/tables.md - - file: editor/adding-an-appendix.md - - file: editor/interactive-outputs.md - - file: editor/videos-and-iframes.md - - title: References & Citations - children: - - file: editor/citations.md - - file: editor/internal-references.md - - file: editor/citation-style.md - - file: editor/reference-style.md - - title: Export - children: - - file: editor/export-microsoft-word.md - - file: editor/export-pdf.md - - file: editor/export-latex.md - - file: editor/export-template-options.md - - file: editor/export-tagging-blocks.md - - file: editor/export-cli-latex-and-pdfs.md - - file: editor/export-cli-jupyter-book.md - - file: editor/export-hosting.md - - title: Jupyter Notebooks - children: - - file: editor/jupyter-overview.md - - file: editor/reproducible-figures.md - - file: editor/interactive-outputs-in-jupyter.md - - file: editor/versioning-notebooks.md - - file: editor/blocks-and-cells.md - - file: editor/reusing-blocks.md - - file: editor/add-and-link-notebooks.md - - file: editor/deleting-notebooks.md - - file: editor/notebook-settings.md - - title: Reference - children: - - file: editor/support.md - - file: editor/data-and-security.md + - file: cli/workflows.md + - file: cli/configuration.md + - file: cli/export.md + - file: cli/deployment.md + - file: cli/troubleshooting.md + - title: Reference children: - file: directives.md - file: glossary.md + - file: integrations/github.md site: template: book-theme options: diff --git a/publishing/deploying-myst-from-github.md b/publishing/deploying-myst-from-github.md new file mode 100644 index 0000000..c4dfc47 --- /dev/null +++ b/publishing/deploying-myst-from-github.md @@ -0,0 +1,212 @@ +--- +title: Deploying to curve.space from GitHub +short_title: Deploying from GitHub +description: Complete guide to deploying Curvenote sites to curve.space using GitHub Actions for automated publishing +--- + +# Deploying to curve.space from GitHub + +Curvenote provides a deployment action in the GitHub Marketplace, allowing you to easily add automated deployment to your repository. This guide takes you through the steps of using GitHub to version your website and collaborate with others, while also using GitHub Actions to deploy your website. + +## Overview + +By the end of this guide, you will understand how to set up automated deployment from GitHub to curve.space, including workflow configuration, secret management, and best practices for continuous deployment. + +## Before You Start + +**Prerequisites:** +- **Curvenote Project**: An initialized Curvenote project in a local folder +- **GitHub Repository**: The local folder must also be a GitHub repository +- **Basic Git Knowledge**: Understanding of Git operations and GitHub workflows + +**Setup Requirements:** +- To initialize your Curvenote project, see [Start with a local folder](./tutorial-deploy-local.md) +- To initialize your Git repository, see GitHub's guides on [git init](https://github.com/git-guides/git-init), [creating a repo](https://docs.github.com/en/get-started/quickstart/create-a-repo), and [managing remotes](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories) + +## 1. Repository Configuration + +After working with a Curvenote website locally, a number of files and folders will be created within your local folder alongside your content. Some of these should be committed to `git`, while others should be ignored. + +**Files to Commit:** +- **`curvenote.yml` files**: Commit all configuration files (root and subfolder configurations) +- **Content files**: All your articles, notebooks, and media files +- **Documentation**: README files and project documentation + +**Files to Ignore:** +- **`_build/` folder**: Add to `.gitignore` - used only for caching local build assets +- **Temporary files**: Any temporary or generated files +- **Environment files**: Local environment configurations + +## 2. GitHub Actions Setup + +Curvenote provides a deployment action in the GitHub Marketplace for automated deployment to your repository. + +**Action Overview:** +The Curvenote Deploy action automatically builds and deploys your site to curve.space whenever you push changes to your main branch. + +**Adding the Workflow:** +1. **Create Workflow File**: Create `.github/workflows/deploy.yml` in your repository +2. **Configure Workflow**: Add the following YAML configuration: + +```yaml +name: Curvenote Deploy +on: + push: + branches: + - main +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Deploy to curve.space + uses: curvenote/action-deploy@v1 + env: + CURVENOTE_TOKEN: ${{ secrets.CURVENOTE_TOKEN }} +``` + +**Workflow Triggers:** +- **Push to main**: Automatically deploys when changes are pushed to the main branch +- **Manual triggers**: Can be configured for manual deployment when needed +- **Pull request previews**: Optional preview deployments for pull requests + +## 3. API Token Configuration + +A Curvenote API token is required for the deployment action to authenticate with Curvenote services. + +**Token Generation:** +1. **Access Curvenote**: Go to [curvenote.com](https://curvenote.com/profile?settings=true&tab=profile-api&subtab=general) +2. **Generate Token**: Create a new API token for your user account +3. **Set Permissions**: Ensure the user account has appropriate team access and rights + +**GitHub Secrets Setup:** +1. **Repository Secrets**: Navigate to your repository settings and add a new repository secret +2. **Secret Name**: Use `CURVENOTE_TOKEN` as the secret name +3. **Secret Value**: Set the value to your API token string +4. **Environment Variables**: The workflow references the secret using `${{ secrets.CURVENOTE_TOKEN }}` + +**Security Best Practices:** +- **Separate Tokens**: Use different tokens for different environments +- **Token Rotation**: Regularly rotate API tokens for security +- **Minimal Permissions**: Use tokens with the minimum required permissions +- **Access Monitoring**: Monitor token usage and revoke unused tokens + +## 4. Deployment Process + +Once configured, the deployment process is fully automated: + +**Automatic Deployment:** +1. **Push Changes**: Commit and push your changes to the main branch +2. **Action Trigger**: GitHub Actions automatically detects the push +3. **Build Process**: Curvenote builds your site with the latest changes +4. **Deployment**: The built site is deployed to curve.space +5. **Status Update**: Success or failure status is reported back to GitHub + +**Deployment Status:** +- **Success ✅**: Content was built and site deployed correctly +- **Failure ❌**: Check the action logs for detailed error information +- **Pending ⏳**: Deployment is in progress + +**Monitoring Deployments:** +- **Actions Tab**: View deployment status in the Actions tab on your repository +- **Logs**: Click on the action to see detailed build and deployment logs +- **Notifications**: Set up notifications for deployment status updates + +## 5. Advanced Configuration + +For more complex deployment scenarios, consider these advanced features: + +**Linked Projects:** +If your website project includes other linked projects on [curvenote.com](https://curvenote.com), you can automatically include the latest changes from those projects on deployment: + +```yaml +steps: + - uses: actions/curvenote-deploy@v1 + with: + pull: true +``` + +**Environment-specific Deployments:** +- **Development**: Deploy to development environments for testing +- **Staging**: Pre-production validation and review +- **Production**: Final deployment to live sites + +**Conditional Deployment:** +- **File-based Triggers**: Deploy only when specific files change +- **Branch-specific Behavior**: Different deployment strategies for different branches +- **User-based Permissions**: Control who can trigger deployments + +## 6. Development Workflows + +In many cases, you'll want to push working changes to Git without triggering a deployment of your site. Here are several strategies: + +**Branch-based Development:** +- **Feature Branches**: Create branches for feature development +- **Pull Requests**: Review changes via pull requests into the main branch +- **Selective Merging**: Only merge when ready to deploy + +**Development Branch Strategy:** +- **Long-lived Dev Branch**: Create a `dev` or `develop` branch for team collaboration +- **Feature Integration**: Regularly integrate feature branches into dev +- **Production Deployment**: Merge dev into main when ready for production + +**Alternative Deployment Branches:** +- **Release Branch**: Deploy from a separate `release` branch instead of main +- **Custom Triggers**: Modify the workflow to deploy from different branches + +```yaml +on: + push: + branches: + - release +``` + +## 7. Troubleshooting + +Common deployment issues and their solutions: + +**Authentication Issues:** +- **Token Validation**: Verify that your API token is valid and not expired +- **Permission Checks**: Ensure the token has the required permissions +- **Repository Access**: Confirm the token can access the target repository +- **Team Membership**: Verify the user account is part of the required team + +**Build Failures:** +- **Configuration Errors**: Check `curvenote.yml` syntax and configuration +- **Dependency Issues**: Verify all required dependencies are available +- **Content Errors**: Check for syntax errors in markdown or notebook files +- **Resource Limits**: Check for resource constraints or rate limiting + +**Deployment Issues:** +- **Network Connectivity**: Ensure stable network connectivity for external services +- **Service Availability**: Check if Curvenote services are available +- **Quota Limits**: Verify you haven't exceeded deployment quotas +- **Domain Configuration**: Check domain and DNS settings + +## 8. Best Practices + +Follow these best practices for effective deployment management: + +**Repository Management:** +- **Clean Commits**: Use meaningful commit messages and clean Git history +- **Branch Protection**: Enable branch protection for main branches +- **Code Review**: Require pull request reviews before merging +- **Version Control**: Use semantic versioning for releases + +**Deployment Strategy:** +- **Automated Testing**: Implement automated testing before deployment +- **Rollback Plans**: Have strategies for quickly rolling back failed deployments +- **Monitoring**: Set up monitoring and alerting for deployment status +- **Documentation**: Keep deployment documentation current + +**Security Considerations:** +- **Secret Management**: Never expose secrets in logs or outputs +- **Access Control**: Limit access to deployment configuration and secrets +- **Token Security**: Rotate tokens regularly and monitor usage +- **Environment Isolation**: Use different tokens for different environments + +## Next Steps + +- [GitHub Actions for Publishing →](./github-actions.md) +- [Managing Submissions using GitHub →](./submissions-using-github.md) +- [Integrated Previews →](./integrated-previews.md) +- [GitHub Integration Reference →](../integrations/github.md) diff --git a/Publish/editorial-process.md b/publishing/editorial-process.md similarity index 62% rename from Publish/editorial-process.md rename to publishing/editorial-process.md index d2811fd..5820ea4 100644 --- a/Publish/editorial-process.md +++ b/publishing/editorial-process.md @@ -1,11 +1,11 @@ --- -title: Publishing Workflow +title: Editorial Process: From Submission to Publication short_title: Editorial Process --- # Publishing Workflow -## Quick Start +## Overview Navigate the complete publishing workflow from submission to publication, including peer review, revisions, and final acceptance through Curvenote's collaborative platform ## Before You Start @@ -85,17 +85,37 @@ Your accepted article becomes publicly available: - **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) +- Learn about [Managing Authors and Contributors](../authoring/manage-authors.md) +- Understand [Export Options](./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 +💡 **Tip:** Set up GitHub notifications for your pull request to stay informed about all comments and changes. Use the "Watch" button on your PR to receive email updates for every activity. + +⚡ **Important: First-Time Publishing Tips** + +**Before Submission:** +- **Test your build locally**: Run `curvenote build` to catch formatting issues before submission +- **Check all links**: Verify that all internal links and external references work correctly +- **Preview your article**: Use `curvenote start` to see exactly how your article will appear +- **Validate metadata**: Ensure all author ORCIDs, affiliations, and DOIs are correct + +**During Review:** +- **Use GitHub's "Resolve" feature**: Mark comments as resolved when you've addressed them +- **Reference specific commits**: When responding to reviewers, mention which commit addresses their concern +- **Keep commits focused**: Make separate commits for different types of changes (formatting vs. content) +- **Test after each major change**: Rebuild and preview after significant revisions + +**Common Pitfalls to Avoid:** +- **Don't force-push**: Use regular commits instead of rewriting history +- **Don't ignore automated checks**: Address all failed checks before requesting review +- **Don't submit incomplete work**: Ensure all sections, figures, and references are complete +- **Don't forget to update the abstract**: If you make significant changes, update your abstract accordingly + +**Pro Tips:** +- **Use draft PRs**: Start with a draft pull request to get early feedback before formal submission +- **Set up branch protection**: Protect your main branch to prevent accidental merges +- **Create a checklist**: Use GitHub's task lists to track what needs to be done +- **Backup your work**: Keep a local copy of your article in case you need to revert changes diff --git a/editor/export-latex.md b/publishing/export-latex.md similarity index 100% rename from editor/export-latex.md rename to publishing/export-latex.md diff --git a/Publish/export-pdf-typst.md b/publishing/export-pdf-typst.md similarity index 99% rename from Publish/export-pdf-typst.md rename to publishing/export-pdf-typst.md index 76d94f1..a2be5a7 100644 --- a/Publish/export-pdf-typst.md +++ b/publishing/export-pdf-typst.md @@ -6,7 +6,7 @@ description: Step-by-step tutorial for exporting your Curvenote scientific paper # Export Your Scientific Paper to PDF and Typst -## Quick Start +## Overview 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. diff --git a/Publish/export-pdf.md b/publishing/export-pdf.md similarity index 99% rename from Publish/export-pdf.md rename to publishing/export-pdf.md index df0cb21..9021abb 100644 --- a/Publish/export-pdf.md +++ b/publishing/export-pdf.md @@ -6,7 +6,7 @@ description: Export and download your Curvenote articles as professional PDF doc # Export Articles as PDF -## Quick Start +## Overview Export your Curvenote articles as professional PDF documents with customizable templates, proper formatting, and publication-ready output ## Before You Start diff --git a/publishing/github-actions.md b/publishing/github-actions.md new file mode 100644 index 0000000..9f2fc71 --- /dev/null +++ b/publishing/github-actions.md @@ -0,0 +1,210 @@ +--- +title: GitHub Actions for Publishing +short_title: GitHub Actions +description: Complete guide to setting up and configuring GitHub Actions for automated publishing workflows with Curvenote +--- + +# GitHub Actions for Publishing + +Curvenote provides GitHub actions to connect your GitHub repository to a Curvenote Site and run your [editorial workflow from pull requests](./submissions-using-github.md). The actions are available on GitHub ([curvenote/actions](https://github.com/curvenote/actions)). + +## Overview + +By the end of this guide, you will understand how to configure GitHub Actions for automated publishing workflows, including preview generation, validation checks, and deployment automation. + +## Before You Start + +**Prerequisites:** +- **Curvenote Site**: You must have an active Curvenote site to use this action (see [Deploying from GitHub](./deploying-myst-from-github.md) for setup) +- **API Token**: A Curvenote API token is required (see [Secret Management](#secret-management) below) +- **GitHub Repository**: A GitHub repository with your Curvenote project +- **Basic GitHub Knowledge**: Understanding of pull requests, issues, and GitHub Actions + +## 1. Basic Workflow Setup + +Start with a basic GitHub Actions workflow for your Curvenote project: + +```yaml +name: curvenote +on: + pull_request: + branches: ['main'] +permissions: + contents: read + pull-requests: write +jobs: + publish: + uses: curvenote/actions/.github/workflows/publish.yml@v1 + with: + monorepo: true + id-pattern-regex: '^-(?:[a-zA-Z0-9-_]{3,15})$' + enforce-single-folder: true + preview-label: paper + submit-label: true + venue: '' + collection: '' + kind: '' + path: papers/* + secrets: + CURVENOTE: ${{ secrets.CURVENOTE_TOKEN }} + GITHUB: ${{ secrets.GITHUB_TOKEN }} +``` + +**Workflow Components:** +- **Strategy**: Determines what actions should be run based on repository structure +- **Preview**: Posts the submission to Curvenote as a draft or ongoing submission +- **Check**: Validates each submission against venue criteria +- **Summary**: Posts information back to the GitHub pull request + +## 2. Action Configuration Options + +Curvenote's integrated previews are highly customizable. You can configure your workflow to generate different types of previews based on your project's needs: + +**Preview Types:** +- **Branch Previews**: Every commit on a branch generates a unique preview, allowing for easy tracking of changes in real-time +- **Pull Request**: When a pull request is opened, a **draft** preview can be generated for review and iteration + +**Key Configuration Parameters:** + +`monorepo` (boolean) +: When `true` indicates that this repository contains multiple projects that should be published. For example, if you have multiple articles, or tutorials that should be previewed and submitted when there are changes in the repository. + +`id-pattern-regex` (string - regex) +: A regular expression that all IDs must follow, by default this matches a UUID. This can be used to enforce that all project IDs follow a specific pattern, such as the conference name + year. The ID must also satisfy alphanumeric characters, dashes, and underscores. + +`enforce-single-folder` (boolean) +: When `true`, an error will be raised if a pull-request is touching multiple different folders. This can either be `true` or a label string. Multiple labels can be added with comma-separated values. If labels are used to control this property, the pull request will only fail in PRs with these labels. + +`preview-label` (string) +: A pull-request label that indicates the preview and checks should be run. Multiple labels can be added with comma-separated values. If no label is supplied, the preview will run on all PRs. + +`submit-label` (string) +: A pull-request label that indicates the branch should be turned into a submission. This will notify all curators of the Curvenote site. The submission identifiers will be written directly to the repository in a commit, and the submission will be available to be merged on the Curvenote platform. + +## 3. Advanced Workflow Features + +For more complex publishing scenarios, consider these advanced features: + +**Multi-Environment Support:** +- **Development**: Preview builds for testing and development +- **Staging**: Pre-production validation and review +- **Production**: Final publication and deployment + +**Conditional Execution:** +- **File-based Triggers**: Run actions only when specific files change +- **Branch-specific Behavior**: Different configurations for different branches +- **User-based Permissions**: Control who can trigger specific actions + +**Integration Options:** +- **External Services**: Connect with other CI/CD tools and services +- **Notification Systems**: Automated alerts for build status and issues +- **Analytics**: Track workflow performance and usage patterns + +## 4. Secret Management + +A Curvenote API token is required for GitHub Actions to authenticate with Curvenote services. + +**Token Generation:** +1. **Access Curvenote**: Go to [curvenote.com](https://curvenote.com/profile?settings=true&tab=profile-api&subtab=general) +2. **Generate Token**: Create a new API token for your user account +3. **Set Permissions**: Ensure the user account has appropriate team access and rights + +**GitHub Secrets Setup:** +1. **Repository Secrets**: Add the token as a secret within your [GitHub Repository or Environment](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) +2. **Secret Name**: Use `CURVENOTE_TOKEN` as the secret name +3. **Environment Variables**: Reference the secret in your workflow using `${{ secrets.CURVENOTE_TOKEN }}` + +**Security Best Practices:** +- **Token Rotation**: Regularly rotate API tokens for security +- **Minimal Permissions**: Use tokens with the minimum required permissions +- **Environment Isolation**: Use different tokens for different environments +- **Access Monitoring**: Monitor token usage and revoke unused tokens + +## 5. Workflow Optimization + +Optimize your GitHub Actions workflows for better performance and reliability: + +**Performance Improvements:** +- **Caching**: Cache dependencies and build artifacts to speed up builds +- **Parallel Execution**: Run independent jobs in parallel when possible +- **Resource Optimization**: Use appropriate runner types and resource limits +- **Build Optimization**: Minimize build time by excluding unnecessary files + +**Reliability Enhancements:** +- **Error Handling**: Implement proper error handling and retry logic +- **Timeout Management**: Set appropriate timeouts for long-running jobs +- **Fallback Strategies**: Provide fallback options for failed builds +- **Monitoring**: Track workflow success rates and performance metrics + +## 6. Troubleshooting Common Issues + +Resolve common GitHub Actions issues with these troubleshooting steps: + +**Authentication Issues:** +- **Token Validation**: Verify that your API token is valid and not expired +- **Permission Checks**: Ensure the token has the required permissions +- **Repository Access**: Confirm the token can access the target repository +- **Team Membership**: Verify the user account is part of the required team + +**Build Failures:** +- **Configuration Errors**: Check workflow syntax and configuration parameters +- **Dependency Issues**: Verify all required dependencies are available +- **Resource Limits**: Check for resource constraints or rate limiting +- **Network Issues**: Ensure stable network connectivity for external services + +**Performance Issues:** +- **Build Time**: Optimize build processes and reduce unnecessary steps +- **Resource Usage**: Monitor resource consumption and optimize accordingly +- **Caching**: Implement effective caching strategies for dependencies +- **Parallelization**: Use parallel execution where possible + +## 7. Best Practices + +Follow these best practices for effective GitHub Actions implementation: + +**Workflow Design:** +- **Modular Structure**: Break complex workflows into smaller, focused jobs +- **Clear Naming**: Use descriptive names for workflows, jobs, and steps +- **Documentation**: Document workflow purpose and configuration options +- **Version Control**: Use specific versions of actions for stability + +**Security Considerations:** +- **Secret Management**: Never expose secrets in logs or outputs +- **Permission Minimization**: Use the minimum required permissions +- **Token Security**: Rotate tokens regularly and monitor usage +- **Access Control**: Limit access to workflow configuration and secrets + +**Maintenance and Monitoring:** +- **Regular Updates**: Keep actions and dependencies up to date +- **Performance Monitoring**: Track workflow performance and optimize as needed +- **Error Tracking**: Monitor and address recurring issues +- **Documentation Updates**: Keep documentation current with workflow changes + +## 8. Integration Examples + +Explore these integration examples for common publishing scenarios: + +**Conference Proceedings:** +- **Multi-author Support**: Handle submissions from multiple authors +- **Review Workflow**: Automated review assignment and tracking +- **Publication Pipeline**: Streamlined publication process +- **Archive Management**: Long-term storage and accessibility + +**Journal Submissions:** +- **Peer Review**: Integrated peer review workflow +- **Editorial Process**: Automated editorial decision tracking +- **Version Control**: Complete submission history and versioning +- **Publication Standards**: Automated compliance checking + +**Lab Group Websites:** +- **Collaborative Writing**: Multi-author collaboration workflows +- **Content Management**: Automated content organization and updates +- **Publication Scheduling**: Controlled publication timing +- **Access Control**: Role-based access to different content areas + +## Next Steps + +- [Managing Submissions using GitHub →](./submissions-using-github.md) +- [Deploying from GitHub →](./deploying-myst-from-github.md) +- [Integrated Previews →](./integrated-previews.md) +- [GitHub Integration Reference →](../integrations/github.md) diff --git a/publishing/submissions-using-github.md b/publishing/submissions-using-github.md new file mode 100644 index 0000000..4040bce --- /dev/null +++ b/publishing/submissions-using-github.md @@ -0,0 +1,148 @@ +--- +title: Managing Submissions using GitHub +short_title: Submissions using GitHub +description: A comprehensive guide for setting up submission repositories for conferences, proceedings, or lab groups using GitHub Actions and Curvenote +--- + +# Managing Submissions using GitHub + +This guide is designed for editorial teams at journals, lab group websites, or personal sites who are managing a focused collection of articles, such as conference proceedings, consortium articles, or lab-group papers. + +## Overview + +By the end of this guide, you will understand how to set up a GitHub repository to accept submissions, conduct open peer-review, make publication decisions, and publish content through Curvenote. + +## Before You Start + +**Prerequisites:** +- **Technical Skills**: Basic understanding of GitHub operations (pull requests, issues, GitHub actions, permission management) +- **Git Knowledge**: Understanding of Git for commits, merges, and branches +- **Access**: Editorial team members should have appropriate access to the GitHub repository and Curvenote Site with Editor or Admin role +- **Starting Point**: A local MyST Project prepared using the [Submitting Your Work](authoring/submitting-your-work.md) guide + +**Required Setup:** +- A Curvenote site to host your content (contact [Curvenote Support](mailto:support@curvenote.com) to create a site for your community) + +## 1. Repository Setup + +The repository on GitHub will serve as the central hub for submissions, reviews, and publications. The repository is organized with a directory dedicated to submissions, such as an `articles` folder. This repository may include a template example that authors can copy. The `README.md` should have brief guidelines for the submissions process to help authors with the expected format of the papers submitted, for example, as LaTeX or MyST Markdown. + +**Getting Started:** +1. **Clone the Template Repository**: Use our [Template Repository](https://github.com/curvenote-examples/proceedings-submissions) which includes basic instructions for authors and a GitHub action that runs on every pull request +2. **Fork the Repository**: Start by forking the template repository to host all submissions, reviews, and accepted papers +3. **Add Team Members**: Add members of your editorial team as collaborators in the repository (you do not need to add prospective authors as they will create pull-requests to add their submissions) + +## 2. Repository Structure + +The template repository includes the following key components: + +**README.md**: Outlines the purpose of the repository, submission instructions, and the review process. It acts as the first point of information for potential contributors and reviewers. + +**Templates**: Located in the `articles` folder, these templates demonstrate to authors how to create submissions. They include placeholders for all required elements such as the title, authors, abstract, sections, and supporting materials. + +**GitHub Action**: Curvenote utilizes GitHub Actions to automate initial checks and generate previews of submissions. The actions automatically generate a preview of the manuscript as it would appear in publication, and these are linked within the pull request comments for easy access by reviewers. + +## 3. GitHub Actions Configuration + +Curvenote's GitHub Actions provide automated workflow management for your submission process: + +**Automated Features:** +- **Initial Checks**: Validation of submission format and requirements +- **Preview Generation**: Automatic creation of publication-ready previews +- **Pull Request Integration**: Seamless integration with GitHub's review process +- **Status Updates**: Real-time feedback on submission status + +**Configuration Options:** +- **Monorepo Support**: Handle multiple submissions in a single repository +- **Custom Validation**: Enforce specific submission requirements and formats +- **Preview Labels**: Control when previews are generated based on pull request labels +- **Submission Workflow**: Automate the transition from review to publication + +## 4. Editorial Workflow + +The GitHub-based editorial workflow streamlines the review and publication process: + +**Submission Process:** +1. **Author Fork**: Authors fork the repository and create feature branches +2. **Pull Request**: Authors submit pull requests with their manuscripts +3. **Automated Checks**: GitHub Actions run validation and generate previews +4. **Review Process**: Reviewers access previews and provide feedback via GitHub +5. **Iteration**: Authors update their submissions based on feedback +6. **Approval**: Once approved, submissions are merged and published + +**Review Management:** +- **Preview Access**: Reviewers can view live previews of submissions +- **Comment Integration**: All feedback is tracked within GitHub pull requests +- **Version Control**: Complete history of changes and iterations +- **Collaboration**: Multiple reviewers can work simultaneously + +## 5. Publication Process + +Once submissions are approved and merged, the publication process is automated: + +**Automated Publication:** +- **Content Building**: Curvenote automatically builds the final publication +- **Site Updates**: Changes are immediately reflected on your Curvenote site +- **Version Management**: All versions are tracked and accessible +- **Distribution**: Published content is available through your configured channels + +**Quality Assurance:** +- **Format Validation**: Ensures all submissions meet publication standards +- **Link Verification**: Checks all internal and external links +- **Content Review**: Final validation before publication +- **Error Handling**: Graceful handling of any publication issues + +## 6. Best Practices + +Follow these best practices for effective submission management: + +**Repository Management:** +- **Clear Documentation**: Provide comprehensive submission guidelines +- **Template Usage**: Use consistent templates for all submissions +- **Version Control**: Maintain clean Git history and meaningful commit messages +- **Access Control**: Manage permissions appropriately for different user roles + +**Workflow Optimization:** +- **Automated Validation**: Leverage GitHub Actions for consistent quality checks +- **Preview Testing**: Test preview generation before going live +- **Feedback Integration**: Use GitHub's review features effectively +- **Performance Monitoring**: Track workflow efficiency and identify bottlenecks + +## 7. Troubleshooting + +Common issues and solutions for GitHub-based submissions: + +**Setup Issues:** +- **Repository Access**: Ensure all team members have appropriate permissions +- **Action Configuration**: Verify GitHub Actions are properly configured +- **Token Management**: Check that API tokens are valid and have correct permissions +- **Template Issues**: Ensure templates are up-to-date and functional + +**Workflow Issues:** +- **Preview Failures**: Check action logs for build or configuration errors +- **Validation Errors**: Review submission requirements and format specifications +- **Permission Problems**: Verify user access and repository settings +- **Integration Issues**: Test GitHub Actions in isolation before full deployment + +## 8. Advanced Configuration + +For more complex submission workflows, consider these advanced features: + +**Custom Validation:** +- **Format Enforcement**: Custom rules for submission structure and content +- **Quality Checks**: Automated validation of figures, references, and metadata +- **Integration Testing**: Comprehensive testing of all submission components +- **Performance Optimization**: Efficient handling of large numbers of submissions + +**Workflow Customization:** +- **Multi-stage Review**: Complex review processes with multiple approval stages +- **Conditional Publication**: Publication rules based on submission characteristics +- **Integration APIs**: Connect with external systems and databases +- **Analytics**: Track submission metrics and workflow performance + +## Next Steps + +- [GitHub Actions for Publishing →](./github-actions.md) +- [Deploying from GitHub →](./deploying-myst-from-github.md) +- [Integrated Previews →](./integrated-previews.md) +- [GitHub Integration Reference →](../integrations/github.md) diff --git a/submissions-using-github.md b/submissions-using-github.md deleted file mode 100644 index c8dbd3a..0000000 --- a/submissions-using-github.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Managing Submissions using GitHub -subtitle: A guide for setting up submission repositories for conferences, proceedings or lab-groups -description: A tutorial on managing an editorial workflow using GitHub Actions and Curvenote. ---- - -This guide is designed for editorial teams at journals, lab group websites, -or personal sites who are managing a focused collection of articles, such as -conference proceedings, consortium articles, or lab-group papers. - -:::{tip} Objective -By the end of this guide you will understand how to setup a GitHub repository -to accept submissions, conduct open peer-review, make publication decisions, -and publish content through Curvenote. - -The recommended starting point for this guide is a local MyST Project that -you have already prepared using the [](./authoring/submitting-your-work.md) guide. -::: - -:::{tip} Prerequisites -:class: dropdown -Technical Skills -: Basic understanding of GitHub operations such as pull requests, issues, GitHub actions and permission management. -: Understanding of Git, for commits, merges, and branches. - -Access -: Editorial team members should have appropriate access to the GitHub repository and the Curvenote Site with an Editor or Admin role. -::: - -## Repository Setup - -The repository on GitHub will serve as the central hub for submissions, reviews, and publications. The repository is organized contains a directory dedicated to submissions, such as a `articles` folder. This repository may include a template example that authors can copy. The `README.md` should have brief guidelines for the submissions process to help authors with the expected format of the papers submitted, for example, as LaTeX or MyST Markdown. - -To get started, you can clone the [Template Repository][template], which includes some basic instructions for authors as well as a GitHub action that will run on every pull request that is tagged appropriately. To get setup, start by forking the [Template Repository][template]. This repository will host all submissions, reviews, and accepted papers. Add members of your editorial team as collaborators in the repository, you do not need to add prospective authors as they will create pull-requests to add their submissions. - -:::{note} Create a Curvenote Site -To move further in the guide, you will need a Curvenote site to host your content. -Contact [Curvenote Support][support] to create a site for your community. -::: - -## Repository and Action Overview - -To help you visualize and implement this setup, you can refer to our [Template Repository][template]. This repository includes: - -- **README.md**: Outlines the purpose of the repository, submission instructions, and the review process. It acts as the first point of information for potential contributors and reviewers. -- **Templates**: Located in the `articles` folder, these templates demonstrate to authors how to create a submissions. It includes placeholders for all required elements such as the title, authors, abstract, sections, and supporting materials. -- **GitHub Action**: Curvenote utilizes GitHub Actions to automate initial checks and generate previews of submissions. The actions automatically generate a preview of the manuscript as it would appear in publication, and these are linked within the pull request comments for easy access by reviewers. - -[template]: https://github.com/curvenote-examples/proceedings-submissions -[support]: mailto:support@curvenote.com diff --git a/update-content.md b/update-content.md new file mode 100644 index 0000000..92f961a --- /dev/null +++ b/update-content.md @@ -0,0 +1,1064 @@ +--- +title: Update Content in Your Site +short_title: Update Content +--- + +# Update Content in Your Site + +## Overview +Learn how to update and maintain content in your Curvenote site, including pulling updates, managing changes, and keeping your site current + +This guide covers the process of updating content in your Curvenote site, from pulling the latest changes from linked projects to managing local modifications and ensuring your site stays current with the latest content and features. + +## Before You Start + +Make sure you have: +- Curvenote CLI installed and authorized +- A local Curvenote project with linked content +- Understanding of basic content management concepts +- Git repository set up (recommended for version control) +- Backup of important local changes + +## 1. Understand Content Update Types + +Learn about different ways content can be updated: + +### Update Categories +```yaml +# Content update types +update_types: + remote_updates: + - "New articles from Curvenote" + - "Updated notebooks" + - "Modified images and media" + - "Configuration changes" + + local_modifications: + - "Custom navigation changes" + - "Local content additions" + - "Configuration tweaks" + - "Custom styling" + + system_updates: + - "Curvenote platform updates" + - "CLI tool improvements" + - "New features and capabilities" + - "Bug fixes and patches" +``` + +### Update Workflow +```mermaid +flowchart TD + A[Check for Updates] --> B{Updates Available?} + B -->|No| C[Site is Current] + B -->|Yes| D[Review Changes] + D --> E[Backup Local Changes] + E --> F[Pull Remote Updates] + F --> G[Resolve Conflicts] + G --> H[Test Site] + H --> I[Deploy Updates] + I --> J[Monitor Performance] +``` + +## 2. Check for Available Updates + +Monitor your site for available updates: + +### Check Update Status +```bash +# Check status of all linked projects +curvenote status + +# Check status of specific project +curvenote status --project project-name + +# Check with detailed output +curvenote status --verbose +``` + +### Update Monitoring Script +```python +# update_monitor.py +import subprocess +import json +from datetime import datetime + +class UpdateMonitor: + def __init__(self): + self.last_check = None + self.update_history = [] + + def check_for_updates(self): + """Check for available updates.""" + try: + result = subprocess.run( + ['curvenote', 'status', '--json'], + capture_output=True, + text=True + ) + + if result.returncode == 0: + status_data = json.loads(result.stdout) + self.last_check = datetime.now() + + updates_available = [] + for project in status_data.get('projects', []): + if project.get('has_updates', False): + updates_available.append({ + 'name': project.get('name'), + 'last_update': project.get('last_update'), + 'changes': project.get('changes', []) + }) + + return updates_available + else: + print(f"Error checking status: {result.stderr}") + return [] + + except Exception as e: + print(f"Exception checking updates: {e}") + return [] + + def log_update_check(self, updates_found): + """Log update check results.""" + self.update_history.append({ + 'timestamp': datetime.now(), + 'updates_found': len(updates_found), + 'details': updates_found + }) + + def get_update_summary(self): + """Get summary of recent update activity.""" + if not self.update_history: + return "No update history available" + + recent_checks = self.update_history[-10:] # Last 10 checks + total_updates = sum(check['updates_found'] for check in recent_checks) + + return { + 'total_checks': len(recent_checks), + 'total_updates_found': total_updates, + 'last_check': self.last_check, + 'average_updates_per_check': total_updates / len(recent_checks) if recent_checks else 0 + } + +# Usage example +monitor = UpdateMonitor() +updates = monitor.check_for_updates() +monitor.log_update_check(updates) + +if updates: + print(f"Found {len(updates)} projects with updates:") + for update in updates: + print(f"- {update['name']}: {len(update['changes'])} changes") +else: + print("No updates available") +``` + +### Automated Update Checking +```bash +# Create a script to check for updates +#!/bin/bash +# check_updates.sh + +echo "Checking for Curvenote updates..." +curvenote status + +if [ $? -eq 0 ]; then + echo "Update check completed successfully" +else + echo "Error checking for updates" + exit 1 +fi +``` + +## 3. Pull Remote Updates + +Update your local content with the latest changes: + +### Basic Pull Operations +```bash +# Pull updates from all linked projects +curvenote pull + +# Pull updates from specific project +curvenote pull --project project-name + +# Pull with confirmation disabled +curvenote pull --yes + +# Pull with clean option (removes local changes) +curvenote pull --clean +``` + +### Pull with Options +```bash +# Pull with specific options +curvenote pull \ + --project my-blog \ + --force \ + --clean \ + --verbose + +# Pull and backup local changes +curvenote pull --backup-local-changes + +# Pull with conflict resolution +curvenote pull --resolve-conflicts auto +``` + +### Pull Workflow Script +```python +# pull_workflow.py +import subprocess +import os +import shutil +from datetime import datetime + +def backup_local_changes(): + """Create backup of local changes before pulling.""" + backup_dir = f"backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}" + + if not os.path.exists(backup_dir): + os.makedirs(backup_dir) + + # Copy content directory + if os.path.exists('content'): + shutil.copytree('content', f"{backup_dir}/content") + + # Copy configuration files + config_files = ['curvenote.yml', '_toc.yml'] + for file in config_files: + if os.path.exists(file): + shutil.copy2(file, backup_dir) + + print(f"Backup created in {backup_dir}") + return backup_dir + +def pull_updates(project_name=None, clean=False, force=False): + """Pull updates with error handling.""" + try: + # Create backup if not using clean option + if not clean: + backup_local_changes() + + # Build pull command + cmd = ['curvenote', 'pull'] + + if project_name: + cmd.extend(['--project', project_name]) + + if clean: + cmd.append('--clean') + + if force: + cmd.append('--force') + + # Execute pull + result = subprocess.run(cmd, capture_output=True, text=True) + + if result.returncode == 0: + print("✓ Updates pulled successfully") + return True + else: + print(f"✗ Pull failed: {result.stderr}") + return False + + except Exception as e: + print(f"Exception during pull: {e}") + return False + +def verify_pull_success(): + """Verify that pull was successful.""" + # Check if content files exist + content_dirs = ['content'] + + for dir_path in content_dirs: + if not os.path.exists(dir_path): + print(f"✗ Content directory missing: {dir_path}") + return False + + # Check if configuration files are valid + try: + subprocess.run(['curvenote', 'check'], check=True) + print("✓ Configuration validation passed") + return True + except subprocess.CalledProcessError: + print("✗ Configuration validation failed") + return False + +# Usage +if __name__ == "__main__": + success = pull_updates(clean=True) + if success: + verify_pull_success() +``` + +## 4. Manage Local Changes + +Handle local modifications and customizations: + +### Local Change Management +```python +# local_changes.py +import os +import git +from pathlib import Path + +class LocalChangeManager: + def __init__(self, repo_path='.'): + self.repo_path = repo_path + self.repo = git.Repo(repo_path) + + def get_local_changes(self): + """Get list of local changes.""" + changes = { + 'modified': [], + 'added': [], + 'deleted': [], + 'untracked': [] + } + + # Get modified files + for item in self.repo.index.diff(None): + changes['modified'].append(item.a_path) + + # Get staged changes + for item in self.repo.index.diff('HEAD'): + changes['modified'].append(item.a_path) + + # Get untracked files + for file_path in self.repo.untracked_files: + changes['untracked'].append(file_path) + + return changes + + def backup_changes(self, backup_dir): + """Backup local changes to specified directory.""" + changes = self.get_local_changes() + + if not any(changes.values()): + print("No local changes to backup") + return + + os.makedirs(backup_dir, exist_ok=True) + + for change_type, files in changes.items(): + if files: + type_dir = os.path.join(backup_dir, change_type) + os.makedirs(type_dir, exist_ok=True) + + for file_path in files: + if os.path.exists(file_path): + dest_path = os.path.join(type_dir, file_path) + os.makedirs(os.path.dirname(dest_path), exist_ok=True) + + if os.path.isfile(file_path): + import shutil + shutil.copy2(file_path, dest_path) + + print(f"Local changes backed up to {backup_dir}") + + def restore_changes(self, backup_dir): + """Restore local changes from backup.""" + if not os.path.exists(backup_dir): + print(f"Backup directory not found: {backup_dir}") + return False + + for change_type in ['modified', 'added', 'untracked']: + type_dir = os.path.join(backup_dir, change_type) + if os.path.exists(type_dir): + for root, dirs, files in os.walk(type_dir): + for file in files: + backup_file = os.path.join(root, file) + relative_path = os.path.relpath(backup_file, type_dir) + target_file = os.path.join(self.repo_path, relative_path) + + os.makedirs(os.path.dirname(target_file), exist_ok=True) + import shutil + shutil.copy2(backup_file, target_file) + + print("Local changes restored from backup") + return True + +# Usage +manager = LocalChangeManager() +changes = manager.get_local_changes() + +if any(changes.values()): + print("Local changes detected:") + for change_type, files in changes.items(): + if files: + print(f" {change_type}: {len(files)} files") + + # Backup changes before pull + manager.backup_changes("backup_local_changes") +``` + +### Conflict Resolution +```python +# conflict_resolver.py +import os +import difflib +import subprocess + +class ConflictResolver: + def __init__(self): + self.conflicts = [] + + def detect_conflicts(self): + """Detect merge conflicts in content.""" + conflicts = [] + + # Check for conflict markers in files + for root, dirs, files in os.walk('content'): + for file in files: + if file.endswith(('.md', '.ipynb')): + file_path = os.path.join(root, file) + if self.has_conflict_markers(file_path): + conflicts.append(file_path) + + self.conflicts = conflicts + return conflicts + + def has_conflict_markers(self, file_path): + """Check if file contains conflict markers.""" + try: + with open(file_path, 'r') as f: + content = f.read() + return any(marker in content for marker in ['<<<<<<<', '=======', '>>>>>>>']) + except Exception: + return False + + def resolve_conflicts(self, strategy='manual'): + """Resolve conflicts using specified strategy.""" + if not self.conflicts: + print("No conflicts detected") + return True + + print(f"Found {len(self.conflicts)} conflicts") + + if strategy == 'auto': + return self.auto_resolve() + else: + return self.manual_resolve() + + def auto_resolve(self): + """Automatically resolve conflicts.""" + for conflict_file in self.conflicts: + print(f"Auto-resolving: {conflict_file}") + + # Simple auto-resolution: keep both versions + with open(conflict_file, 'r') as f: + content = f.read() + + # Remove conflict markers and keep both versions + resolved_content = self.remove_conflict_markers(content) + + with open(conflict_file, 'w') as f: + f.write(resolved_content) + + return True + + def manual_resolve(self): + """Guide user through manual conflict resolution.""" + for conflict_file in self.conflicts: + print(f"\nConflict in: {conflict_file}") + print("Please resolve conflicts manually and press Enter to continue...") + input() + + return True + + def remove_conflict_markers(self, content): + """Remove Git conflict markers from content.""" + lines = content.split('\n') + resolved_lines = [] + in_conflict = False + + for line in lines: + if line.startswith('<<<<<<<') or line.startswith('=======') or line.startswith('>>>>>>>'): + in_conflict = not in_conflict + continue + + if not in_conflict: + resolved_lines.append(line) + + return '\n'.join(resolved_lines) + +# Usage +resolver = ConflictResolver() +conflicts = resolver.detect_conflicts() + +if conflicts: + print(f"Found {len(conflicts)} conflicts to resolve") + resolver.resolve_conflicts(strategy='manual') +else: + print("No conflicts detected") +``` + +## 5. Test Updated Content + +Validate your updated content before deployment: + +### Content Testing +```bash +# Test local site +curvenote start + +# Build site for testing +curvenote build + +# Validate configuration +curvenote check + +# Test specific components +curvenote test --component navigation +curvenote test --component links +``` + +### Automated Testing Script +```python +# test_updated_content.py +import subprocess +import time +import requests +from pathlib import Path + +class ContentTester: + def __init__(self): + self.test_results = {} + + def test_build(self): + """Test if site builds successfully.""" + print("Testing site build...") + + start_time = time.time() + result = subprocess.run(['curvenote', 'build'], capture_output=True, text=True) + build_time = time.time() - start_time + + if result.returncode == 0: + self.test_results['build'] = { + 'status': 'passed', + 'time': build_time, + 'message': 'Site builds successfully' + } + print(f"✓ Build successful in {build_time:.2f} seconds") + return True + else: + self.test_results['build'] = { + 'status': 'failed', + 'error': result.stderr, + 'message': 'Build failed' + } + print(f"✗ Build failed: {result.stderr}") + return False + + def test_configuration(self): + """Test configuration validity.""" + print("Testing configuration...") + + result = subprocess.run(['curvenote', 'check'], capture_output=True, text=True) + + if result.returncode == 0: + self.test_results['config'] = { + 'status': 'passed', + 'message': 'Configuration is valid' + } + print("✓ Configuration is valid") + return True + else: + self.test_results['config'] = { + 'status': 'failed', + 'error': result.stderr, + 'message': 'Configuration has issues' + } + print(f"✗ Configuration issues: {result.stderr}") + return False + + def test_content_structure(self): + """Test content structure and files.""" + print("Testing content structure...") + + issues = [] + + # Check for required files + required_files = ['index.md', 'curvenote.yml'] + for file in required_files: + if not Path(file).exists(): + issues.append(f"Missing required file: {file}") + + # Check markdown files + md_files = list(Path('content').rglob('*.md')) + for md_file in md_files: + if md_file.stat().st_size == 0: + issues.append(f"Empty markdown file: {md_file}") + + if not issues: + self.test_results['structure'] = { + 'status': 'passed', + 'message': 'Content structure is valid' + } + print("✓ Content structure is valid") + return True + else: + self.test_results['structure'] = { + 'status': 'failed', + 'issues': issues, + 'message': 'Content structure has issues' + } + print(f"✗ Content structure issues: {issues}") + return False + + def test_local_server(self, port=8000): + """Test local development server.""" + print(f"Testing local server on port {port}...") + + try: + # Start server in background + server_process = subprocess.Popen( + ['curvenote', 'start', '--port', str(port)], + stdout=subprocess.PIPE, + stderr=subprocess.PIPE + ) + + # Wait for server to start + time.sleep(5) + + # Test server response + response = requests.get(f'http://localhost:{port}', timeout=10) + + if response.status_code == 200: + self.test_results['server'] = { + 'status': 'passed', + 'message': 'Local server is working' + } + print("✓ Local server is working") + success = True + else: + self.test_results['server'] = { + 'status': 'failed', + 'status_code': response.status_code, + 'message': 'Local server not responding correctly' + } + print(f"✗ Server returned status {response.status_code}") + success = False + + # Stop server + server_process.terminate() + server_process.wait() + + return success + + except Exception as e: + self.test_results['server'] = { + 'status': 'failed', + 'error': str(e), + 'message': 'Local server test failed' + } + print(f"✗ Server test failed: {e}") + return False + + def run_all_tests(self): + """Run all content tests.""" + tests = [ + self.test_build, + self.test_configuration, + self.test_content_structure, + self.test_local_server + ] + + results = [] + for test in tests: + try: + result = test() + results.append(result) + except Exception as e: + print(f"Test failed with exception: {e}") + results.append(False) + + all_passed = all(results) + + if all_passed: + print("\n🎉 All tests passed!") + else: + print("\n❌ Some tests failed") + + return all_passed, self.test_results + +# Usage +tester = ContentTester() +success, results = tester.run_all_tests() + +if success: + print("Content is ready for deployment") +else: + print("Content needs fixes before deployment") +``` + +## 6. Deploy Updates + +Deploy your updated content to production: + +### Deployment Process +```bash +# Deploy to Curvenote +curvenote deploy + +# Deploy with specific options +curvenote deploy --project my-site --public + +# Deploy to custom domain +curvenote deploy --domain mysite.com + +# Deploy with preview +curvenote deploy --preview +``` + +### Deployment Script +```python +# deploy_updates.py +import subprocess +import time +import requests + +class UpdateDeployer: + def __init__(self, project_name=None, domain=None): + self.project_name = project_name + self.domain = domain + + def deploy(self, preview=False, public=True): + """Deploy updates to Curvenote.""" + print("Deploying updates...") + + # Build command + cmd = ['curvenote', 'deploy'] + + if self.project_name: + cmd.extend(['--project', self.project_name]) + + if self.domain: + cmd.extend(['--domain', self.domain]) + + if preview: + cmd.append('--preview') + + if public: + cmd.append('--public') + + # Execute deployment + start_time = time.time() + result = subprocess.run(cmd, capture_output=True, text=True) + deploy_time = time.time() - start_time + + if result.returncode == 0: + print(f"✓ Deployment successful in {deploy_time:.2f} seconds") + + # Extract deployment URL from output + deployment_url = self.extract_deployment_url(result.stdout) + if deployment_url: + print(f"Deployment URL: {deployment_url}") + + return True, deployment_url + else: + print(f"✗ Deployment failed: {result.stderr}") + return False, None + + def extract_deployment_url(self, output): + """Extract deployment URL from command output.""" + lines = output.split('\n') + for line in lines: + if 'curve.space' in line or 'curvenote.com' in line: + return line.strip() + return None + + def verify_deployment(self, url, timeout=60): + """Verify deployment is accessible.""" + print(f"Verifying deployment at {url}...") + + start_time = time.time() + while time.time() - start_time < timeout: + try: + response = requests.get(url, timeout=10) + if response.status_code == 200: + print("✓ Deployment verified and accessible") + return True + except requests.RequestException: + pass + + time.sleep(5) + + print("✗ Deployment verification failed") + return False + + def rollback_deployment(self): + """Rollback to previous deployment if needed.""" + print("Rolling back deployment...") + + cmd = ['curvenote', 'deploy', '--rollback'] + if self.project_name: + cmd.extend(['--project', self.project_name]) + + result = subprocess.run(cmd, capture_output=True, text=True) + + if result.returncode == 0: + print("✓ Rollback successful") + return True + else: + print(f"✗ Rollback failed: {result.stderr}") + return False + +# Usage +deployer = UpdateDeployer(project_name="my-site") +success, url = deployer.deploy(preview=False, public=True) + +if success and url: + deployer.verify_deployment(url) +``` + +## 7. Monitor and Maintain + +Keep your site running smoothly after updates: + +### Performance Monitoring +```python +# performance_monitor.py +import time +import requests +import psutil +import subprocess + +class PerformanceMonitor: + def __init__(self, site_url): + self.site_url = site_url + self.metrics = [] + + def measure_load_time(self): + """Measure site load time.""" + try: + start_time = time.time() + response = requests.get(self.site_url, timeout=30) + load_time = time.time() - start_time + + metric = { + 'timestamp': time.time(), + 'load_time': load_time, + 'status_code': response.status_code, + 'content_length': len(response.content) + } + + self.metrics.append(metric) + + if load_time < 3: + print(f"✓ Fast load time: {load_time:.2f}s") + elif load_time < 10: + print(f"⚠ Moderate load time: {load_time:.2f}s") + else: + print(f"✗ Slow load time: {load_time:.2f}s") + + return metric + + except Exception as e: + print(f"✗ Load time measurement failed: {e}") + return None + + def check_system_resources(self): + """Check system resource usage.""" + cpu_percent = psutil.cpu_percent() + memory_percent = psutil.virtual_memory().percent + disk_percent = psutil.disk_usage('/').percent + + print(f"System resources - CPU: {cpu_percent}%, Memory: {memory_percent}%, Disk: {disk_percent}%") + + return { + 'cpu': cpu_percent, + 'memory': memory_percent, + 'disk': disk_percent + } + + def generate_performance_report(self): + """Generate performance report.""" + if not self.metrics: + return "No metrics available" + + load_times = [m['load_time'] for m in self.metrics if m['load_time']] + + if load_times: + avg_load_time = sum(load_times) / len(load_times) + max_load_time = max(load_times) + min_load_time = min(load_times) + + report = { + 'total_measurements': len(self.metrics), + 'average_load_time': avg_load_time, + 'max_load_time': max_load_time, + 'min_load_time': min_load_time, + 'performance_rating': self.get_performance_rating(avg_load_time) + } + + return report + + return "No valid load time measurements" + +# Usage +monitor = PerformanceMonitor("https://mysite.curve.space") +monitor.measure_load_time() +monitor.check_system_resources() +report = monitor.generate_performance_report() +print(f"Performance report: {report}") +``` + +### Maintenance Schedule +```yaml +# maintenance_schedule.yml +maintenance_tasks: + daily: + - "Check for updates" + - "Monitor site performance" + - "Review error logs" + + weekly: + - "Pull latest updates" + - "Test site functionality" + - "Backup content" + - "Update dependencies" + + monthly: + - "Review content structure" + - "Optimize performance" + - "Update documentation" + - "Security audit" + + quarterly: + - "Major content review" + - "Site redesign planning" + - "Feature updates" + - "User feedback analysis" +``` + +## 8. Troubleshoot Update Issues + +Handle common update problems: + +### Common Issues and Solutions +```python +# update_troubleshooter.py +import subprocess +import os +import json + +class UpdateTroubleshooter: + def __init__(self): + self.issues = [] + + def diagnose_common_issues(self): + """Diagnose common update issues.""" + print("Diagnosing update issues...") + + # Check CLI installation + if not self.check_cli_installation(): + self.issues.append("CLI not properly installed") + + # Check authorization + if not self.check_authorization(): + self.issues.append("Not authorized with Curvenote") + + # Check network connectivity + if not self.check_network(): + self.issues.append("Network connectivity issues") + + # Check project configuration + if not self.check_project_config(): + self.issues.append("Project configuration issues") + + return self.issues + + def check_cli_installation(self): + """Check if CLI is properly installed.""" + try: + result = subprocess.run(['curvenote', '--version'], capture_output=True, text=True) + return result.returncode == 0 + except FileNotFoundError: + return False + + def check_authorization(self): + """Check if user is authorized.""" + try: + result = subprocess.run(['curvenote', 'whoami'], capture_output=True, text=True) + return result.returncode == 0 + except Exception: + return False + + def check_network(self): + """Check network connectivity.""" + try: + import requests + response = requests.get('https://curvenote.com', timeout=10) + return response.status_code == 200 + except Exception: + return False + + def check_project_config(self): + """Check project configuration.""" + required_files = ['curvenote.yml'] + for file in required_files: + if not os.path.exists(file): + return False + return True + + def fix_common_issues(self): + """Attempt to fix common issues.""" + fixes_applied = [] + + for issue in self.issues: + if "CLI not properly installed" in issue: + print("Installing CLI...") + # Add CLI installation commands + fixes_applied.append("CLI installation") + + elif "Not authorized" in issue: + print("Re-authorizing...") + subprocess.run(['curvenote', 'login']) + fixes_applied.append("Re-authorization") + + elif "Project configuration" in issue: + print("Fixing project configuration...") + # Add configuration fix commands + fixes_applied.append("Configuration fix") + + return fixes_applied + +# Usage +troubleshooter = UpdateTroubleshooter() +issues = troubleshooter.diagnose_common_issues() + +if issues: + print(f"Found {len(issues)} issues:") + for issue in issues: + print(f"- {issue}") + + fixes = troubleshooter.fix_common_issues() + print(f"Applied {len(fixes)} fixes") +else: + print("No issues detected") +``` + +## Next Steps + +- [Learn about Adding Content →](./adding-content.md) +- [Customize Site Design →](./site-design/layout-and-theme.md) +- [Configure Navigation →](./site-design/navigation.md) +- [Deploy Your Site →](./tutorial-deploy-project.md) +- [Manage Multiple Projects →](./sites/index.md) + +--- + +💡 **Tip:** Always backup your local changes before pulling updates, and test your site thoroughly after any major updates. + +⚡ **Important: Update Management Best Practices** + +- **Backup first**: Always backup local changes before pulling updates +- **Test thoroughly**: Validate content and functionality after updates +- **Monitor performance**: Track site performance after updates +- **Version control**: Use Git to track changes and enable rollbacks +- **Document changes**: Keep records of what was updated and when +- **Plan updates**: Schedule updates during low-traffic periods From 1344550dbe7dabce66ff84e727d65e885881239d Mon Sep 17 00:00:00 2001 From: Franklin Koch Date: Thu, 28 Aug 2025 02:34:58 -0600 Subject: [PATCH 2/2] quick start -> overview --- authoring/citations.md | 2 +- authoring/figures-and-images.md | 2 +- authoring/link-data-code.md | 2 +- authoring/organize-content.md | 2 +- authoring/reuse-blocks.md | 2 +- authoring/version-history.md | 2 +- cli/authentication.md | 2 +- cli/commands.md | 2 +- cli/configuration.md | 2 +- cli/deployment.md | 2 +- cli/export.md | 2 +- cli/index.md | 2 +- cli/installing-prerequisites.md | 2 +- cli/installing.md | 2 +- cli/troubleshooting.md | 2 +- cli/workflows.md | 2 +- editor/add-and-link-notebooks.md | 2 +- editor/interactive-outputs.md | 2 +- getting-started/create-a-site.md | 2 +- getting-started/create-article-cli.md | 2 +- getting-started/create-project.md | 2 +- getting-started/install-cli.md | 2 +- quick-start/1-install.md | 2 +- quick-start/2-first-project.md | 2 +- quick-start/3-publish.md | 2 +- quick-start/4-examples.md | 2 +- quick-start/index.md | 2 +- site-design/custom-domains.md | 2 +- site-design/layout-and-theme.md | 2 +- site-design/navigation.md | 2 +- site-design/planning.md | 2 +- 31 files changed, 31 insertions(+), 31 deletions(-) diff --git a/authoring/citations.md b/authoring/citations.md index 2b799ce..1765982 100644 --- a/authoring/citations.md +++ b/authoring/citations.md @@ -5,7 +5,7 @@ short_title: Citations # Add Citations and References -## Quick Start +## Overview 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. diff --git a/authoring/figures-and-images.md b/authoring/figures-and-images.md index 654c24e..d7736e4 100644 --- a/authoring/figures-and-images.md +++ b/authoring/figures-and-images.md @@ -5,7 +5,7 @@ short_title: Figures & Images # Add Figures, Images, and Media -## Quick Start +## Overview 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. diff --git a/authoring/link-data-code.md b/authoring/link-data-code.md index a0be732..30eeb42 100644 --- a/authoring/link-data-code.md +++ b/authoring/link-data-code.md @@ -5,7 +5,7 @@ short_title: Link Data & Code # Link Data and Code -## Quick Start +## Overview 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. diff --git a/authoring/organize-content.md b/authoring/organize-content.md index ef6ffa6..b2a1e4f 100644 --- a/authoring/organize-content.md +++ b/authoring/organize-content.md @@ -5,7 +5,7 @@ short_title: Organize Content # Organize Content into Sections -## Quick Start +## Overview 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. diff --git a/authoring/reuse-blocks.md b/authoring/reuse-blocks.md index ae2e9b6..385d78c 100644 --- a/authoring/reuse-blocks.md +++ b/authoring/reuse-blocks.md @@ -5,7 +5,7 @@ short_title: Reuse Blocks # Reuse Text, Figures, and Blocks -## Quick Start +## Overview 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. diff --git a/authoring/version-history.md b/authoring/version-history.md index eb34306..f280d11 100644 --- a/authoring/version-history.md +++ b/authoring/version-history.md @@ -5,7 +5,7 @@ short_title: Version History # Track Versions and Drafts -## Quick Start +## Overview 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. diff --git a/cli/authentication.md b/cli/authentication.md index 6ad6f9b..f33f868 100644 --- a/cli/authentication.md +++ b/cli/authentication.md @@ -5,7 +5,7 @@ short_title: Authentication # Authentication and API Tokens -## Quick Start +## Overview Set up authentication to access private Curvenote content, sync projects, and deploy websites using API tokens 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. diff --git a/cli/commands.md b/cli/commands.md index fcc825c..dad0537 100644 --- a/cli/commands.md +++ b/cli/commands.md @@ -5,7 +5,7 @@ short_title: Commands # CLI Commands Reference -## Quick Start +## Overview Learn the essential Curvenote CLI commands for creating projects, building content, and deploying websites 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 --help` for specific command options. diff --git a/cli/configuration.md b/cli/configuration.md index db9dc9a..5aa01c5 100644 --- a/cli/configuration.md +++ b/cli/configuration.md @@ -5,7 +5,7 @@ short_title: Configuration # Configure Curvenote Projects -## Quick Start +## Overview 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. diff --git a/cli/deployment.md b/cli/deployment.md index 58215d9..f518e8c 100644 --- a/cli/deployment.md +++ b/cli/deployment.md @@ -5,7 +5,7 @@ short_title: Deployment # Deploy Curvenote Sites -## Quick Start +## Overview 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. diff --git a/cli/export.md b/cli/export.md index 073dc00..252b9a7 100644 --- a/cli/export.md +++ b/cli/export.md @@ -5,7 +5,7 @@ short_title: Export # Export Curvenote Content -## Quick Start +## Overview 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. diff --git a/cli/index.md b/cli/index.md index cdf51aa..9692a35 100644 --- a/cli/index.md +++ b/cli/index.md @@ -5,7 +5,7 @@ short_title: Overview # Curvenote CLI Overview -## Quick Start +## Overview 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. diff --git a/cli/installing-prerequisites.md b/cli/installing-prerequisites.md index 292b3b2..0263d2e 100644 --- a/cli/installing-prerequisites.md +++ b/cli/installing-prerequisites.md @@ -5,7 +5,7 @@ short_title: Node.js Setup # Install Node.js Prerequisites -## Quick Start +## Overview Install Node.js version 14 or higher to use the Curvenote CLI for creating and managing scientific content Node.js is the JavaScript runtime required to run the Curvenote CLI. Choose the installation method that best fits your system and workflow preferences. diff --git a/cli/installing.md b/cli/installing.md index bd8d9d1..a784cdb 100644 --- a/cli/installing.md +++ b/cli/installing.md @@ -5,7 +5,7 @@ short_title: Install CLI # Install Curvenote CLI -## Quick Start +## Overview 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. diff --git a/cli/troubleshooting.md b/cli/troubleshooting.md index f07571d..c52f546 100644 --- a/cli/troubleshooting.md +++ b/cli/troubleshooting.md @@ -5,7 +5,7 @@ short_title: Troubleshooting # Troubleshoot CLI Issues -## Quick Start +## Overview 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. diff --git a/cli/workflows.md b/cli/workflows.md index b69d5a9..02b73d9 100644 --- a/cli/workflows.md +++ b/cli/workflows.md @@ -5,7 +5,7 @@ short_title: Workflows # CLI Workflows and Development -## Quick Start +## Overview 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. diff --git a/editor/add-and-link-notebooks.md b/editor/add-and-link-notebooks.md index e8ddf3d..596155b 100644 --- a/editor/add-and-link-notebooks.md +++ b/editor/add-and-link-notebooks.md @@ -5,7 +5,7 @@ short_title: Add & Link Notebooks # Add & Link Notebooks -## Quick Start +## Overview 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. diff --git a/editor/interactive-outputs.md b/editor/interactive-outputs.md index ca58805..ccb1305 100644 --- a/editor/interactive-outputs.md +++ b/editor/interactive-outputs.md @@ -5,7 +5,7 @@ short_title: Interactive Outputs # Add Interactive Outputs -## Quick Start +## Overview Use Jupyter notebook outputs as interactive figures in your Curvenote articles with automatic versioning and updates Curvenote is built to work hand in hand with Jupyter and allows you to directly use outputs from Jupyter as figures within your Curvenote articles. The versioning in Curvenote also allows for you to easily update your image in the article, rather than having to copy-and-paste a new static image each time you update your code. diff --git a/getting-started/create-a-site.md b/getting-started/create-a-site.md index f897d7f..3759af7 100644 --- a/getting-started/create-a-site.md +++ b/getting-started/create-a-site.md @@ -5,7 +5,7 @@ short_title: Create a Site # Create a Site -## Quick Start +## Overview Set up your Curvenote site to publish and share your work online Creating a Curvenote site gives you a dedicated space to publish your research, lab work, or any scientific content. The process is simple and handled through our onboarding form. diff --git a/getting-started/create-article-cli.md b/getting-started/create-article-cli.md index f46cdd0..4585ce4 100644 --- a/getting-started/create-article-cli.md +++ b/getting-started/create-article-cli.md @@ -5,7 +5,7 @@ short_title: Write Article # Write Your First Article -## Quick Start +## Overview Create and edit your first article in Curvenote using the CLI Writing articles in Curvenote is straightforward and flexible. You can use Markdown, Jupyter notebooks, or other formats to create rich, interactive content. diff --git a/getting-started/create-project.md b/getting-started/create-project.md index c09f419..ad8b817 100644 --- a/getting-started/create-project.md +++ b/getting-started/create-project.md @@ -5,7 +5,7 @@ short_title: Create Project # Create Your First Project -## Quick Start +## Overview Create and organize your first Curvenote project to start writing and publishing content A **project** is the container for everything you want to publish in Curvenote — including articles, figures, datasets, media, and the configuration that controls how they appear online. diff --git a/getting-started/install-cli.md b/getting-started/install-cli.md index fe42a71..9217003 100644 --- a/getting-started/install-cli.md +++ b/getting-started/install-cli.md @@ -5,7 +5,7 @@ short_title: Install CLI # Install & Authenticate the Curvenote CLI -## Quick Start +## Overview Get the Curvenote CLI installed and authenticated in minutes The Curvenote CLI lets you create, manage, and publish content from your terminal. Follow these steps to get up and running quickly. diff --git a/quick-start/1-install.md b/quick-start/1-install.md index 24145e8..4586431 100644 --- a/quick-start/1-install.md +++ b/quick-start/1-install.md @@ -5,7 +5,7 @@ short_title: Install # Install Curvenote -## Quick Start +## Overview 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. diff --git a/quick-start/2-first-project.md b/quick-start/2-first-project.md index 784cd16..7b1052e 100644 --- a/quick-start/2-first-project.md +++ b/quick-start/2-first-project.md @@ -5,7 +5,7 @@ short_title: First Project # Create Your First Project -## Quick Start +## Overview 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. diff --git a/quick-start/3-publish.md b/quick-start/3-publish.md index 4483a1b..aa1b8d9 100644 --- a/quick-start/3-publish.md +++ b/quick-start/3-publish.md @@ -5,7 +5,7 @@ short_title: Publish # Publish Your Site -## Quick Start +## Overview 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. diff --git a/quick-start/4-examples.md b/quick-start/4-examples.md index 54acd29..e9e64a6 100644 --- a/quick-start/4-examples.md +++ b/quick-start/4-examples.md @@ -5,7 +5,7 @@ short_title: Examples # Common Examples -## Quick Start +## Overview 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. diff --git a/quick-start/index.md b/quick-start/index.md index bbd7cdb..f994e39 100644 --- a/quick-start/index.md +++ b/quick-start/index.md @@ -5,7 +5,7 @@ short_title: Quick Start # Quick Start Guide -## Quick Start +## Overview 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. diff --git a/site-design/custom-domains.md b/site-design/custom-domains.md index 2de1c7b..565b997 100644 --- a/site-design/custom-domains.md +++ b/site-design/custom-domains.md @@ -6,7 +6,7 @@ description: Configure your own domain name for your Curvenote site # Set Up Custom Domains -## Quick Start +## Overview 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. diff --git a/site-design/layout-and-theme.md b/site-design/layout-and-theme.md index 43bfe54..9fd93b1 100644 --- a/site-design/layout-and-theme.md +++ b/site-design/layout-and-theme.md @@ -5,7 +5,7 @@ short_title: Layout & Theme # Choose a Layout & Theme -## Quick Start +## Overview 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. diff --git a/site-design/navigation.md b/site-design/navigation.md index 3f8f4a2..18d585a 100644 --- a/site-design/navigation.md +++ b/site-design/navigation.md @@ -6,7 +6,7 @@ description: Configure navigation menus, action buttons, and site structure for # Set Up Site Navigation -## Quick Start +## Overview 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. diff --git a/site-design/planning.md b/site-design/planning.md index 8ae56aa..b10359c 100644 --- a/site-design/planning.md +++ b/site-design/planning.md @@ -5,7 +5,7 @@ short_title: Site Planning # Plan Your Site Design -## Quick Start +## Overview 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.