To author using Ximera, you must have a GitHub account. GitHub is a web platform where developers can store, share, and manage their code. It uses git, popular software for version control, to help teams work together simultaneously without overwriting each other’s changes. GitHub has

• issue tracking,
• pull requests for proposing changes,
• the ability to merge code,

and other project management tools. It’s like a shared folder for coding, designed to help teams work together and track progress. Go to https://github.com and either sign-up or log-in. Note, you must know your username and password, so store them in a safe place; like in a safe, or under your bed. After you have a GitHub account, log-in and go to:

You will see something like this:

Click on the green “Use this template” button and select “Create a new repository.” Give it a fun repository name, and push the button “Create repository.” At this point you have your own personal copy of our repository ximeraFirstSteps. In fact, after you create it, GitHub will take you to it. This copy can always be found at:

For the example used in this manual, the URL would be:

When at your repository, click the green “Code” button, select the “Codespaces” tab, and click “Create codespace on main.” A GitHub codespace is a remote computer set up specifically for coding. It will take around 5 minutes for your codespace to be created and you must wait until it is complete. We have our codespace preconfigured with all the tools, libraries, and software you need to use Ximera. With a codespace, you can instantly start working without worrying about setting up software on your local machine. Moreover, Ximera developers can go to your GitHub page, start their own codespace, and try out your code and directly help with possible issues.

Once the codespace is created, you will see something like what we have above. This is Visual Studio Code (VS Code) running within your browser. VS Code is a powerful text-editor with many extensions. We use it write Ximera content. On the far left, you see a vertical list of icons. Currently, “EXPLORER” is selected, it looks like “pages of paper.” Moving right, we see the files in our GitHub repository. At the bottom right-hand corner of the screen you will see buttons that say “SERVE,” “HTML,” and “PDF.” These buttons were added by the files in the hidden folder .vscode/.

The “SERVE” button

compiles the entire Ximera repository to HTML and deploys to a (local or remote) server. If this is the first time you are compiling, it will take a few minutes.

The “HTML” button

compiles only the current LaTeX file to HTML.

The “PDF” button

compiles only the current LaTeX file to PDF using our Ximera tools.

At this point, you will want to press the“‘SERVE” button. This will compile the entire repository and deploy it to a local server. As part of this process, we will generate a GPG Key, that we use to help sign content online. If you are simply playing with Ximera, you can just hit “enter” twice.

We will discuss deploying Ximera content to the open web in a later section.

After you have pressed the “SERVE” button, you will see a “terminal” window at the bottom of the screen. note the line that says: “PROBLEMS,” “OUTPUT,” “DEBUG CONSOLE,” “TERMINAL,” “PORTS.” You want to click on “PORTS.” The “PORTS” tab may be hidden within “\(\cdots \).” After you click on “PORTS,” select 2080 and click on the globe, and a webpage will open. Your content will be under the link “Content.” You should be able to see the content in your browser.

You may delete your codespace (you can simply recreate it) and others can come to your GitHub repository, start a codespace, and check out and compile your code. This is especially useful if a user runs into difficulty, as a Ximera developer can examine a users exact setup, and help resolve any issues.

Demo versions of this repository are published as:

• a preview with the newest Ximera layout
• a version on the current production server