{"version":3,"kind":"Article","sha256":"9ef10b195de156c8cf0fb457858fa4e910c8effaf662c7703526487269737ab7","slug":"advanced-start","location":"/content/advanced_start.md","dependencies":[],"frontmatter":{"title":"Advanced start 🌶","content_includes_title":false,"authors":[{"nameParsed":{"literal":"Freek Pols","given":"Freek","family":"Pols"},"name":"Freek Pols","id":"contributors-myst-generated-uid-0"},{"nameParsed":{"literal":"Luuk Fröling","given":"Luuk","family":"Fröling"},"name":"Luuk Fröling","id":"contributors-myst-generated-uid-1"},{"nameParsed":{"literal":"Robert Lanzafame","given":"Robert","family":"Lanzafame"},"name":"Robert Lanzafame","id":"contributors-myst-generated-uid-2"},{"nameParsed":{"literal":"Kirstie Whitaker","given":"Kirstie","family":"Whitaker"},"name":"Kirstie Whitaker","id":"contributors-myst-generated-uid-3"},{"nameParsed":{"literal":"Jim Madge","given":"Jim","family":"Madge"},"name":"Jim Madge","id":"contributors-myst-generated-uid-4"}],"date":"2025-11-02","license":{"content":{"id":"CC-BY-4.0","url":"https://creativecommons.org/licenses/by/4.0/","name":"Creative Commons Attribution 4.0 International","free":true,"CC":true}},"github":"https://github.com/jupyter-book/workshop-template","edit_url":null,"abbreviations":{"JB2":"Jupyter Book 2","CI/CD":"Continuous Integration/Continuous Deployment","GHA":"GitHub Actions","GH":"GitHub","IDE":"Integrated Development Environment","VSC":"Visual Studio Code","CLI":"commmand line interface"},"source_url":"https://github.com/jupyter-book/workshop-template/blob/main/content/advanced_start.md","exports":[{"format":"md","filename":"advanced_start.md","url":"/build/advanced_start-483b6aa8d94ef6881459292883ba8747.md"}]},"mdast":{"type":"root","children":[{"type":"div","class":"font-light text-sm mb-4 updated-date-container","children":[{"type":"text","value":"Updated: 03 Nov 2025","key":"ATIJI21a6X"}],"key":"Mhu10C3iwv"},{"type":"block","children":[{"type":"paragraph","position":{"start":{"line":4,"column":1},"end":{"line":4,"column":1}},"children":[{"type":"text","value":"The Jupyter Book and MyST ","key":"ortJVHKS8g"},{"type":"abbreviation","title":"commmand line interface","children":[{"type":"text","value":"CLI","key":"MIFgBeGL4z"}],"key":"xXlATcgNZO"},{"type":"text","value":"s both include tools to help get started writing quickly. You might want to follow this approach if:","key":"fGBRzq9eCD"}],"key":"RQAp6SlC2Z"},{"type":"list","ordered":false,"spread":false,"position":{"start":{"line":6,"column":1},"end":{"line":10,"column":1}},"children":[{"type":"listItem","spread":true,"position":{"start":{"line":6,"column":1},"end":{"line":6,"column":1}},"children":[{"type":"paragraph","children":[{"type":"text","value":"You are already familiar with using Markdown dialects to build documents and websites","position":{"start":{"line":6,"column":1},"end":{"line":6,"column":1}},"key":"QmG9nBTgyK"}],"key":"E9Ic6mEpTV"}],"key":"WKl7c5V1E9"},{"type":"listItem","spread":true,"position":{"start":{"line":7,"column":1},"end":{"line":7,"column":1}},"children":[{"type":"paragraph","children":[{"type":"text","value":"You have previously used Jupyter Book 1","position":{"start":{"line":7,"column":1},"end":{"line":7,"column":1}},"key":"foFemWGjBC"}],"key":"mz1WddUL64"}],"key":"hdCNg8sInX"},{"type":"listItem","spread":true,"position":{"start":{"line":8,"column":1},"end":{"line":8,"column":1}},"children":[{"type":"paragraph","children":[{"type":"text","value":"You are comfortable working with command line tools and reading documentation","position":{"start":{"line":8,"column":1},"end":{"line":8,"column":1}},"key":"VG8oZzMdOO"}],"key":"ZcgJWPpjT7"}],"key":"mAkvjbg52e"},{"type":"listItem","spread":true,"position":{"start":{"line":9,"column":1},"end":{"line":10,"column":1}},"children":[{"type":"paragraph","children":[{"type":"text","value":"You don’t like waiting for GitHub Actions to see updates to your book as you edit it","position":{"start":{"line":9,"column":1},"end":{"line":9,"column":1}},"key":"EFV7pDsiTe"}],"key":"HfE8bP93Yy"}],"key":"UaCFc5QuZR"}],"key":"L4ysjqcmxY"},{"type":"paragraph","position":{"start":{"line":11,"column":1},"end":{"line":11,"column":1}},"children":[{"type":"text","value":"The ","position":{"start":{"line":11,"column":1},"end":{"line":11,"column":1}},"key":"m9tgrN2pcz"},{"type":"link","url":"https://mystmd.org/guide","position":{"start":{"line":11,"column":1},"end":{"line":11,"column":1}},"children":[{"type":"text","value":"MyST Markdown guide","position":{"start":{"line":11,"column":1},"end":{"line":11,"column":1}},"key":"e8dv6jwilq"}],"urlSource":"https://mystmd.org/guide","key":"eNeLFJC4z5"},{"type":"text","value":" will be a valuable resource if you follow this route.","position":{"start":{"line":11,"column":1},"end":{"line":11,"column":1}},"key":"Zv0qNaFB88"}],"key":"EeQiLs8PSm"},{"type":"heading","depth":2,"position":{"start":{"line":13,"column":1},"end":{"line":13,"column":1}},"children":[{"type":"text","value":"Install Jupyter Book","position":{"start":{"line":13,"column":1},"end":{"line":13,"column":1}},"key":"YBd3tuuMQQ"}],"identifier":"install-jupyter-book","label":"Install Jupyter Book","html_id":"install-jupyter-book","implicit":true,"key":"XZHM5U8yGS"},{"type":"paragraph","position":{"start":{"line":15,"column":1},"end":{"line":16,"column":1}},"children":[{"type":"text","value":"There are ","position":{"start":{"line":15,"column":1},"end":{"line":15,"column":1}},"key":"OInqCbbDez"},{"type":"link","url":"https://next.jupyterbook.org/start/install/","position":{"start":{"line":15,"column":1},"end":{"line":15,"column":1}},"children":[{"type":"text","value":"a number of options for installing Jupyter Book","position":{"start":{"line":15,"column":1},"end":{"line":15,"column":1}},"key":"MCTBJmcvZF"}],"urlSource":"https://next.jupyterbook.org/start/install/","key":"hK7lLFVPO8"},{"type":"text","value":".\nTwo common methods are using ","position":{"start":{"line":15,"column":1},"end":{"line":15,"column":1}},"key":"MjsbyDCY9U"},{"type":"inlineCode","value":"pip","position":{"start":{"line":15,"column":1},"end":{"line":15,"column":1}},"key":"k3NYxeX5DR"}],"key":"ClCOoJuxh8"},{"type":"code","lang":"console","value":"pip install \"jupyter-book>=2.0.0\"","position":{"start":{"line":18,"column":1},"end":{"line":20,"column":1}},"key":"wa4y4NRhIQ"},{"type":"paragraph","position":{"start":{"line":22,"column":1},"end":{"line":22,"column":1}},"children":[{"type":"text","value":"or ","position":{"start":{"line":22,"column":1},"end":{"line":22,"column":1}},"key":"N5ns37foQt"},{"type":"inlineCode","value":"npm","position":{"start":{"line":22,"column":1},"end":{"line":22,"column":1}},"key":"UtjAYpAoyA"}],"key":"AItsPv99v8"},{"type":"code","lang":"console","value":"npm install -g \"jupyter-book@>=2.0.0-a0\"","position":{"start":{"line":24,"column":1},"end":{"line":26,"column":1}},"key":"ZwAe0GTmI8"},{"type":"admonition","kind":"hint","children":[{"type":"admonitionTitle","children":[{"type":"text","value":"Hint","key":"ilHAHWGfQF"}],"key":"ukF1hXJC2l"},{"type":"paragraph","position":{"start":{"line":29,"column":1},"end":{"line":29,"column":1}},"children":[{"type":"text","value":"Note the version specifications, which ensure the MyST-based Jupyter Book 2 is installed, not the Sphinx-based Jupyter Book 1.","position":{"start":{"line":29,"column":1},"end":{"line":29,"column":1}},"key":"QS7UYP06mJ"}],"key":"Yh75wWxs9h"}],"key":"ijwmRwbED2"},{"type":"heading","depth":2,"position":{"start":{"line":32,"column":1},"end":{"line":32,"column":1}},"children":[{"type":"text","value":"Initialise a project with ","key":"BUB3JxooR8"},{"type":"abbreviation","title":"commmand line interface","children":[{"type":"text","value":"CLI","key":"Rt2XKNPfhU"}],"key":"N5vDfi0vHR"}],"identifier":"initialise-a-project-with-cli","label":"Initialise a project with CLI","html_id":"initialise-a-project-with-cli","implicit":true,"key":"JFwEvTmeSJ"},{"type":"paragraph","position":{"start":{"line":34,"column":1},"end":{"line":34,"column":1}},"children":[{"type":"text","value":"To initialise a Jupyter Book project, use the ","key":"bKUBHzmNLb"},{"type":"abbreviation","title":"commmand line interface","children":[{"type":"text","value":"CLI","key":"LqGehLU6HB"}],"key":"ZJnaVrPjek"}],"key":"SaP0i4BFeL"},{"type":"code","lang":"console","value":"jupyter-book init","position":{"start":{"line":36,"column":1},"end":{"line":38,"column":1}},"key":"EN44Kc6yZR"},{"type":"paragraph","position":{"start":{"line":40,"column":1},"end":{"line":41,"column":1}},"children":[{"type":"text","value":"This will create a basic book, including the ","position":{"start":{"line":40,"column":1},"end":{"line":40,"column":1}},"key":"jGK05330ex"},{"type":"inlineCode","value":"myst.yml","position":{"start":{"line":40,"column":1},"end":{"line":40,"column":1}},"key":"tNz4QiwaPr"},{"type":"text","value":" file.\nYou can serve your book locally","position":{"start":{"line":40,"column":1},"end":{"line":40,"column":1}},"key":"BHxRzcRQOp"}],"key":"B9kqtKs60N"},{"type":"code","lang":"console","value":"jupyter-book start","position":{"start":{"line":43,"column":1},"end":{"line":45,"column":1}},"key":"fpwlJY739y"},{"type":"paragraph","position":{"start":{"line":47,"column":1},"end":{"line":47,"column":1}},"children":[{"type":"text","value":"Open ","position":{"start":{"line":47,"column":1},"end":{"line":47,"column":1}},"key":"aIeLuGfatd"},{"type":"link","url":"http://localhost:3000","position":{"start":{"line":47,"column":1},"end":{"line":47,"column":1}},"children":[{"type":"inlineCode","value":"http://localhost:3000","position":{"start":{"line":47,"column":1},"end":{"line":47,"column":1}},"key":"r4Hvit3S1b"}],"urlSource":"http://localhost:3000","key":"dpqDkJyhAO"},{"type":"text","value":" in your browser to see the output.","position":{"start":{"line":47,"column":1},"end":{"line":47,"column":1}},"key":"vXIr03Zn0E"}],"key":"VwWZvyPb25"},{"type":"heading","depth":2,"position":{"start":{"line":50,"column":1},"end":{"line":50,"column":1}},"children":[{"type":"text","value":"Edit the content","position":{"start":{"line":50,"column":1},"end":{"line":50,"column":1}},"key":"LvybPJASu0"}],"identifier":"edit-the-content","label":"Edit the content","html_id":"edit-the-content","implicit":true,"key":"NGSjEmNsYu"},{"type":"paragraph","position":{"start":{"line":52,"column":1},"end":{"line":52,"column":1}},"children":[{"type":"text","value":"You can edit the content files in the ","position":{"start":{"line":52,"column":1},"end":{"line":52,"column":1}},"key":"JvTG50AAv9"},{"type":"inlineCode","value":"content","position":{"start":{"line":52,"column":1},"end":{"line":52,"column":1}},"key":"ADl3VAbgUH"},{"type":"text","value":" directory using your text editor and see the output immediately updated in your browser at the local server address (you may need to refresh the page when changes are made).","position":{"start":{"line":52,"column":1},"end":{"line":52,"column":1}},"key":"Mvg7yeyBKB"}],"key":"XTZJ4rMA9r"},{"type":"paragraph","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"children":[{"type":"text","value":"You may want to follow ","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"key":"yYbdR2CTGg"},{"type":"link","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"children":[{"type":"text","value":"the lessons here","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"key":"kqzYR36VuE"}],"identifier":"lessons-start","label":"lessons-start","url":"/your-turn","internal":true,"dataUrl":"/your-turn.json","key":"KppsUBFkTe"},{"type":"text","value":" or experiment yourself with the ","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"key":"pw6gcavpMM"},{"type":"link","url":"https://mystmd.org/guide","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"children":[{"type":"text","value":"MyST Markdown guide","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"key":"Uxt7aPANvJ"}],"urlSource":"https://mystmd.org/guide","key":"mlUhziqWV4"},{"type":"text","value":".","position":{"start":{"line":54,"column":1},"end":{"line":54,"column":1}},"key":"hPbxYlJX3B"}],"key":"zEHBTc9nhO"},{"type":"heading","depth":2,"position":{"start":{"line":56,"column":1},"end":{"line":56,"column":1}},"children":[{"type":"text","value":"Deploy to GitHub pages","position":{"start":{"line":56,"column":1},"end":{"line":56,"column":1}},"key":"wEVvdoAPrn"}],"identifier":"deploy-to-github-pages","label":"Deploy to GitHub pages","html_id":"deploy-to-github-pages","implicit":true,"key":"S2K6X1onrf"},{"type":"paragraph","position":{"start":{"line":58,"column":1},"end":{"line":58,"column":1}},"children":[{"type":"text","value":"The ","key":"nK63w3HDYD"},{"type":"abbreviation","title":"commmand line interface","children":[{"type":"text","value":"CLI","key":"p4FZvpbE77"}],"key":"eEUbvYPbbX"},{"type":"text","value":" can also prepare a GitHub workflow to deploy your book to GitHub Pages, similar to the template.","key":"W2SRYwshnJ"}],"key":"yQFxWVNeVH"},{"type":"code","lang":"console","value":"jupyter-book init --gh-pages","position":{"start":{"line":60,"column":1},"end":{"line":62,"column":1}},"key":"fcGHvxBDhM"},{"type":"paragraph","position":{"start":{"line":64,"column":1},"end":{"line":64,"column":1}},"children":[{"type":"text","value":"The command will print instructions to finish setting up GitHub Pages.","position":{"start":{"line":64,"column":1},"end":{"line":64,"column":1}},"key":"pBvmqScY9z"}],"key":"wAQsaaBgrI"}],"key":"ET5C7PA1Lz"}],"key":"xHdqed2X4K"},"references":{"cite":{"order":[],"data":{}}},"footer":{"navigation":{"prev":{"title":"Empty book","url":"/init","group":"Jupyter Book 2 Workshop Template"},"next":{"title":"Software","url":"/software","group":"Jupyter Book 2 Workshop Template"}}},"domain":"http://localhost:3000"}