Over the past few months, we've been busy building an open source Command Line Interface (CLI) that sits on top of our content translation schemas and talks to the Curvenote API. We've put a lot of time and care into the design of the Curvenote CLI to make it easy to use and so you can get results quickly. In this post, we will dive into the main capabilities of the Curvenote CLI.
Installing the Curvenote CLI¶
npm install -g curvenote
You can learn more about installing Node or NPM if those tools aren’t familiar.
The CLI can work completely locally on your content and files. It can also connect and synchronize with the Curvenote API (learn how to get an API key), opening up collaborations between folks working online in the Curvenote editor, in the Curvenote Jupyter extension, or locally through the command line.
The CLI provides a simple development experience for writing content and publishing websites designed for open science publications — whether that's a preprint or paper, materials for a whole research project or a full Ph.D. thesis. Other examples include:
- Courses & books
- Seminar & conference websites
- Blogs & technical websites
- Papers & reports
- Sharing Jupyter Notebooks
Key commands for building websites locally are:
curvenote init- initialize your folder with a
curvenote start- build your website, start a local web server, and open a preview in your web browser (this preview will update in real time as you update content!)
curvenote deploy- deploy your website to Curvenote's free hosting services
Provided you already have content in Markdown files or Juptyer Notebooks, you can get a website started, previewed, and deployed to the web in just a few minutes.
Here is a demo where Rowan got a full live demo done in 2 minutes and 54 seconds. 🚀
Cloning Curvenote Projects¶
The CLI works with both local content and content online in Curvenote projects. The latter is made possible by Curvenote's API and underlying version control. You can pull in content from projects that you collaborate on with others, save new versions of your work, and update exiting projects with both content and website configuration information.
At the moment there are two commands that allow you to sync content. Those are
pull, which fetch new content to a local folder and fetch updates for an existing local folder respectively.
First, let’s take a look at
curvenote clone <https://curvenote.com/@username/my-project>
For example, try
curvenote clone https://curvenote.com/@templates/web
This command can behave in one of two ways:
- Run this in an empty folder and this will fetch the project's existing
siteconfiguration and content enabling you to work on this locally and deploy manually.
- Run this in an initialized local folder (i.e. one containing a
siteconfiguration) and this will add the project as an additional section in your existing website, fetching the content and updating your website's navigation controls in the process.
The first allows update and manual deployment of any existing website either by another user or by an automated system (e.g. through the Curvenote GitHub Action), where the entire site configuration and latest versions of content is retrieved in full with a single command.
The second case enables powerful content aggregation workflows when publishing, allowing someone with the CLI to build documents or websites based on content from multiple collaborating users or groups, even when permission to access that content may be different on each project (of course, the CLI user must have access to all). An example of such a publication is the SWUNG Transform Conference Website which was built from the Curvenote projects and GitHub repositories of many different groups of authors.
Next, let’s take a look at
pull, which can only be run from within an initialized folder:
curvenote pull [optional/content/path]
This command allows you to pull the latest updates for content in all projects, or a specific project or document if the optional path is provided.
We're extending the CLI to expose Curvenote's full version control capabilities (i.e.
push). This will enable:
- a round trip of files and content with conflict resolution, allowing authors working locally to work with others concurrently no matter if they are working locally themselves or in the online editor
- the ability to add and push new files including images and other supported files to Curvenote projects, enabling workflows where visualizations and figures are generated outside of Jupyter notebooks.
Stay tuned for updates on twitter!
Exporting Content to Word, PDF, LaTeX, MyST and more¶
The last CLI service we'll talk about is
curvenote export. This exposes functionality from Curvenote's open source schema, nbtx, and prosemirror extensions which constitute a powerful document translation engine. It is used to build Markdown (MyST), HTML, DOCX, ipynb, jupyter-books, LaTeX and PDF files locally from a Curvenote article.
See the list of commands below:
When dealing with LaTeX and PDF exports you can also use templates from Curvenote's Public Template Repository and create documents ready for submission to a number of preprint services and scientific journals.
For more details on how to use the
export service and dependencies that you may need to run some commands see our documentation.
Right now export commands only work with Curvenote projects, where content is pulled directly from the API into a temporary folder and built. We are currently changing this to support building from a local folder as well as support multi-article export (e.g. a PhD thesis or large report).
We've built out detailed documentation at https://curvenote.com/docs, covering everything that we talked about in this post.
See the Curvenote CLI in action¶
Watch our recent webinar on Creating an Open Research Website where we go from a folder of Markdown files and Jupyter Notebooks to a published website in a few minutes, before exploring the customizations we can make to change navigation, add more content, add licenses, DOIs, binder links and more.
Other resources from Curvenote tagged cli
Curvenote and MyST websites create structured data, which can be rendered by any number of "theme servers", which are in charge of turning that structured data into a reading experience.
Webinar - Learn how to write your next paper, report or even your thesis in MyST Markdown to create PDFs and interactive web articles.
Export your Curvenote articles to MyST Markdown to locally edit the content. MyST Markdown is a new specification of Markdown that allows you to write professional documents, books and websites.
We added thumbnails to the article frontmatter, as well as met up with the whole Curvenote team in person for the first time!
We overhauled the curvenote.com site to make better use of the new publishing tools and CLI.
We added all sorts of scholarly metadata, including licenses, DOIs, arXiv links, open access statements, binder & GitHub links, and more.