{"id":43611716,"url":"https://github.com/berkeley-cdss/course-site-myst","last_synced_at":"2026-02-04T12:07:59.430Z","repository":{"id":199800463,"uuid":"703787333","full_name":"berkeley-cdss/course-site-myst","owner":"berkeley-cdss","description":"A MyST-based course website template","archived":false,"fork":false,"pushed_at":"2025-08-06T20:32:33.000Z","size":620,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-06T22:18:49.065Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/berkeley-cdss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-11T23:24:39.000Z","updated_at":"2025-08-06T20:32:36.000Z","dependencies_parsed_at":"2023-11-25T05:19:21.392Z","dependency_job_id":"d927f196-d4a9-4cc4-a870-a49d2b6177b6","html_url":"https://github.com/berkeley-cdss/course-site-myst","commit_stats":null,"previous_names":["berkeley-scf/stat999-myst","berkeley-scf/course-site-myst","berkeley-cdss/course-site-myst"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/berkeley-cdss/course-site-myst","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeley-cdss%2Fcourse-site-myst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeley-cdss%2Fcourse-site-myst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeley-cdss%2Fcourse-site-myst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeley-cdss%2Fcourse-site-myst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/berkeley-cdss","download_url":"https://codeload.github.com/berkeley-cdss/course-site-myst/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeley-cdss%2Fcourse-site-myst/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29084091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T03:31:03.593Z","status":"ssl_error","status_checked_at":"2026-02-04T03:29:50.742Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-04T12:07:59.353Z","updated_at":"2026-02-04T12:07:59.414Z","avatar_url":"https://github.com/berkeley-cdss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# course-site-myst\n\nThis repository contains a MyST-based template for class website. You can see a preview of it at [https://berkeley-cdss.github.io/course-site-myst](https://berkeley-cdss.github.io/course-site-myst). This template is intended to be forked and altered for other courses.\n\n## Capabilities of this MyST-based Template\n\n- Create a website by modifying content in a GitHub repository.\n- Create documents from markdown files or Jupyter notebooks.\n- Include LaTeX and LaTeX macros for mathematical notation.\n- Embed live python kernels via JupyterLite.\n- Embed external webpages (such as Google calendars) as iframes within a page.\n- Render documents as HTML or PDF (the latter for documents that students will download).\n- Render a schedule from a YAML file.\n- MyST Markdown includes various nice features such as automatic navigation links, callouts, tables, images, code blocks, diagrams, etc. It also has a plugin system which enables you to create custom features.\n\n\n## Terminology\n\n- \"Rendering\" a document or a site involves converting the *source* markdown or notebook files to html.\n- \"Previewing\" a site involves rendering the site and displaying it locally on your computer (i.e., at `localhost:\u003cport\u003e` in a web browser.\n- \"Publishing\" a site involves pushing the rendered site to the `gh-pages` branch of the GitHub repository so it can be viewed at the public URL.\n\n\n## Workflow Overview\n\n### Centralized Workflow\n\nThe simplest workflow is where departmental staff fork this template or a previous semester's repo into a new one. The instructor (and course staff of their choosing) are given permission to make changes.\n\nFor example, given the class repo https://github.com/berkeley-stat555/fall-2024 :\n\n```mermaid\n%% State diagram documentation at\n%% https://mermaid.js.org/syntax/stateDiagram.html\n\nstateDiagram-v2\n    repo_template: github.com/berkeley-cdss/course-site-myst\n    repo_dept: github.com/berkeley-stat555/fall-2024\n    website_dept: stat555.berkeley.edu/fall-2024\n\n    repo_template --\u003e repo_dept: Departmental staff fork template\\nor previous term's repo.\n    repo_dept --\u003e website_dept: Course staff directly push changes which go live.\n```\n\n### Fork and Pull Request Workflow\n\nAnother method involves course staff forking the class repo into their own GitHub account. They would then make pull requests in the class repo, and following feedback, discussion, alterations, etc., authorized staff could merge the PRs. This gives the instructor or repo admin a bit more control over changes.\n\nFor example, given the instructor with GitHub handle `@paciorek` and the shared class repo https://github.com/berkeley-stat555/fall-2024 :\n\n```mermaid\n%% State diagram documentation at\n%% https://mermaid.js.org/syntax/stateDiagram.html\n\nstateDiagram-v2\n    repo_template: github.com/berkeley-cdss/course-site-myst\n    repo_dept: github.com/berkeley-stat555/fall-2024\n    repo_i: github.com/paciorek/stat555-fall-2024\n    website_dept: stat555.berkeley.edu/fall-2024\n\n    repo_template --\u003e repo_dept: Departmental staff fork template\\nor previous term's repo.\n    repo_dept --\u003e repo_i: Contributor forks\\nclass repo.\n    repo_i --\u003e repo_dept: Contributor creates a PR which\\ninitiates a review.\n    repo_dept --\u003e website_dept: Course repo admin merges,\\nand changes go live.\n```\n\n\n## Instructions for Course Staff\n\nThese instructions have been tested under macOS.\n\n### Edit the Content\n\n1. When department staff notify you that the class repository is ready, clone it into a local working directory on your computer. For the purposes of these instructions, we'll pretend your repository is at https://github.com/berkeley-stat555/fall-2024.\n   - You can do this from the terminal/commandline or within a Git graphical application (e.g., `GitHub Desktop`).\n   - From the terminal it would look like this:\n     ```bash\n     git clone https://github.com/berkeley-stat555/fall-2024\n     cd fall-2024\n     ```\n   If you need to maintain several of these websites and there is a conflict in working directory names, you can just rename the working directory after cloning it, e.g. `mv fall-2024 stat555-fall-2024; cd stat555-fall-2024`.\n\n\n1. Begin making changes relevant to your course.\n   - Modify the site's metadata in `myst.yml`. Notable fields include the course title, description, author, and GitHub URL. You can also edit links to external resources for your course, such as bCourses and Ed.\n   - Modify the table of contents in `_toc.yml` to reflect the structure you want.\n   - Update `README.md` to remove all the instructions we provide (i.e., this text you are reading!).\n   - Edit the other markdown files in the working directory and add new markdown or jupyter notebook files as desired.\n   - Update `index.md` to reflect the material you want displayed in the main page.\n   - You can make use of various MyST features discussed in the [MyST Guide](https://mystmd.org/guide).\n\n\n1. Update your repository with the changes to your source files. First tell git about all files that should be in your repo.\n\n   ```bash\n   git add NEWFILE1.md NEWFILE2.md NEWDIRECTORY\n   ```\n\n   Then commit your changes:\n   ```bash\n   git commit -m \"Initial checkin for Stat 555.\"\n   ```\n\n   If you modify an existing file, you can either do `git add currentfile.md` or include the `-a` flag when you run `git commit` to automatically update files that Git is already keeping track of, e.g., after modifying unit 7 files, `git commit -am \"Updated Unit 7\"`.\n\n\n### Preview Changes (Optional)\n\nIf you want to preview the website locally on your own computer before they go live, follow these instructions. It is not strictly necessary, but we recommend doing so to spot errors. If you are confident that your changes will not break anything (for example for quick fixes), you can skip this section.\n\n1. Install a Conda distribution, such as [Miniforge](https://github.com/conda-forge/miniforge) or [Anaconda](https://www.anaconda.com/download#downloads), if you don't already have one installed.\n\n\n1. Install software using conda/mamba and npm. To preview the website on your own device you will need some command-line programs such as `nodejs` and [myst](https://mystmd.org/guide/quickstart). We have provided `environment.yml` and `packages.json` to make this step simpler. Run the commands below to install all dependencies in a separate environment, and then activate it. This keeps your website development separate from any other projects you're working on.\n     ```bash\n     # You can replace `mamba` with `conda`.\n     mamba env create -f environment.yml\n     \n     # Use `packages.json` to install JavaScript packages.\n     npm install\n\n     # Now you can activate the environment.\n     # You can use `mamba activate` or `conda activate`,\n     # but these require that you have run `mamba init` or `conda init`,\n     # which modifies your shell.\n     mamba activate stat-myst-site\n     \n     # Alternatively, you can activate like this, without\n     # having do the `init` step mentioned above.\n     source activate stat-myst-site\n     ```\n\n   Whenever you need to start up a new terminal to work on your website, first activate the the environment that contains the necessary programs with `mamba activate stat-myst-site`. Otherwise your terminal may report that it cannot find `myst` or its dependencies.\n\n\n1. Preview your changes on your own device. Run `myst init` in the working directory to initialize your working directory. When prompted, let the command run `myst start` for you to generate a preview. `myst` will display a localhost URL where the site preview is running, such as http://localhost:3000. Open this URL in your browser.\n\n   **Note:** When `myst` detects problems in the markdown that prevent the website from rendering correctly, it will print the file and line number containing the issue. If this happens, fix the file and rerun `myst init`.\n\n   **Note:** If you are on a Mac, `myst` may prompt you to allow `node` to accept incoming network connection. Allow this to enable website previewing to work.\n\n   You can leave `myst` running as you make changes to the source files; saving changes to the source files will generally will be reflected live in your browser, though you may sometimes need to navigate away and back or reload the page.\n\n   You can also run `myst build` to create the static HTML (in the `_build` directory) without automatically displaying it.\n\n   **Note:** Do not commit the files in `_build` to your repository. They will not be used when the website is deployed. Rather, an automated process via GitHub Actions will run and create the static build files.\n\n\n### Push Your Changes to Publish\n\n1. Push your changed to GitHub:\n   ```bash\n   git push\n   ```\n   This will cause GitHub to rebuild your site.\n\n1.  You can observe the build process at GitHub by clicking on the Actions button at the top of your repository, e.g. https://github.com/berkeley-stat555/fall-2024/actions. It usually takes a couple of minutes for this to complete.\n\n2. If there are no problems, your website will be publicly available at https://stat555.berkeley.edu/fall-2024.\n\n\nStaff are happy to help. Please [contact us](https://statistics.berkeley.edu/computing/how-get-help) if you are a Berkeley Statistics instructor and you run into problems or questions.\n\n\n## Instructions for Department Staff\n\n1. Create a GitHub organization for the course if one does not already exist. It should be named `berkeley-statNNN` where `NNN` is the course number.\n\n1. If it was necessary to create a new GitHub organization, create a course overview repository and website as well.\n\n   a. Instantiate the template at https://github.com/berkeley-cdss/course-overview into the new organization.\n\n   a. Complete the course overview section and make other course-specific adjustments.\n\n   a. Create a .stat subdomain CNAME for statNNN.stat.berkeley.edu for the course in DNS if one does not already exist. See GitHub's [instructions](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).\n\n   a. Add the CNAME to https://github.com/berkeley-statNNN/course-overview/settings/pages \u003e Custom domain. This will add a `CNAME` file to the repository.\n\n   a. Request a top-level CNAME for statNNN.berkeley.edu pointing at statNNN.stat.berkeley.edu.\n\n1. Fork this `course-site-myst` repository template:\n\n   a. Visit https://github.com/berkeley-cdss/course-site-myst.\n\n   b. Above the file list click **Use this template** and then **Create a new repository**. This will then bring you to a screen where you'll configure the new repository.\n\n   c. Do not enable the **Include all branches** checkbox.\n\n   d. Name the repository after academic term, e.g. `fall-2024` and place it into the per-course organization, e.g. `berkeley-statNNN`.\n\n   e. You might choose the default of having your repository be public or choose that it be private while you are setting things up. Or you might choose for it always to be private.\n\n   f. Click on **Create Repository**.\n\n   g. Replace this README with the content shown in the next section.\n\n1. Enable GitHub Pages in the repository. Go to Settings \u003e Pages \u003e Source \u003e GitHub Actions (Beta). Because a GitHub action is contained within the template, it will run when the template is instantiated and may fail until this step is completed.\n\n### README Content for Actual Class Repositories\n\nThis is the repository for the course website and course material for Department 555 for Fall 2024.\nThe website for which this content is the source materials is available at\n\u003chttps://{ course hostname}/fall-2024\u003e.\n\nFor instructors: please see [these instructions](https://github.com/berkeley-cdss/course-site-myst#instructions-for-course-staff) on how to use this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkeley-cdss%2Fcourse-site-myst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberkeley-cdss%2Fcourse-site-myst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkeley-cdss%2Fcourse-site-myst/lists"}