LlamaMagic.net Build Status Discord

Static site at llamamagic.net using Material for MkDocs.

Editing

ℹ️ Most editors only need this section!

To submit changes to the site,

  1. Fork this repository to make your own copy.
  2. Edit content in .md text files and git commit + git push.
  3. Submit a pull request to get your work published on the real site!

This site is written in Markdown, the same formatting used on GitHub, Reddit, Discord, etc. You can easily edit directly on GitHub or with a text editor such as Visual Studio Code.

Some advanced MkDocs features may not preview correctly on GitHub or in VS Code — see the Development section for fully-rendered local previews.

Tips

  • Reference-style links are recommended to move URLs elsewhere in the file, which makes it easier to read + edit raw content, reuse links in multiple locations, and update links in one spot.
  • src/snippets/common-links.md defines a list of common links included in all pages. If something should be linked across many pages, or if a definition seems “missing” from a file, check common-links.md. You may need to restart Docker to pick up links added here.

Development

Setup

Main article: Getting Started with MkDocs

For easy local development, the customized Material for MkDocs container includes all dependencies and plugins used by the site.

  1. Install Docker.
  2. git clone [email protected]:LlamaMagic/llamamagic.github.io.git
  3. cd ./llamamagic.github.io
  4. pwsh ./run.ps1
  5. Visit http://127.0.0.1:8000/ for a fully-rendered preview that auto-reloads on save.

Deployment

ℹ️ Only site administrators need this section.

This site is deployed to GitHub Pages as an “organization site” (versus user or project site).

Configuring GitHub Pages

Main article: Getting Started with GitHub Pages

  1. On the GitHub repo page, go to Settings > Pages.
  2. Under Source, set Branch: gh-pages and Folder: / (root), then click Save.
  3. Wait for site to fully publish to the URL at the top of the page.

Customizing the Domain Name

Main article: Configuring Custom Domains

  1. On the GitHub repo page, go to Settings > Pages.
  2. Set Custom Domain: llamamagic.net, then click Save.
  3. git pull the CNAME file created by GitHub into src/docs/.
  4. At your domain name provider, configure DNS records:
    • Create CNAME record for www as llamamagic.github.io
    • Create A and AAAA records for @ as GitHub Pages’ IPv4 and IPv6 addresses.

Publishing Changes

Main article: Publishing Your Site

Automatic builds + publishing are triggered by pushing commits to master branch.

Changes should appear on the site after a few minutes. Check the Actions tab for build status and error logs.

⚠️ All MkDocs plugins added to the Dockerfile must also be added to Publish.yml or the automated build will fail.

GitHub

View Github