{"id":19108012,"url":"https://github.com/zml/docs","last_synced_at":"2025-09-06T22:38:11.366Z","repository":{"id":257568389,"uuid":"854624718","full_name":"zml/docs","owner":"zml","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-01T14:48:17.000Z","size":5823,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-09-06T10:58:15.786Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","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/zml.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":"2024-09-09T13:58:05.000Z","updated_at":"2025-04-15T03:31:48.000Z","dependencies_parsed_at":"2025-02-16T13:42:12.915Z","dependency_job_id":"e46d1b6d-1bfa-4210-97e9-bfe82ee3f8e3","html_url":"https://github.com/zml/docs","commit_stats":null,"previous_names":["zml/docs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zml/docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zml%2Fdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zml%2Fdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zml%2Fdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zml%2Fdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zml","download_url":"https://codeload.github.com/zml/docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zml%2Fdocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273973969,"owners_count":25200578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2024-11-09T04:14:47.659Z","updated_at":"2025-09-06T22:38:11.345Z","avatar_url":"https://github.com/zml.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docs\n\n## REQUIREMENTS:\n\n- zig 0.13.0\n\n## HOW TO EDIT WITH LIVE-PREVIEW \u0026 COMMIT DOCS\n\n```console\nzig build tool -- clone          # clones zml into the current directory (gitignored)\nzig build tool -- edit           # prepares a WORKSPACE dir for editing\nzig build tool -- build serve    # builds the zine website and serves it\n```\n\nNow, you can edit all `.smd` files, as well as `.shtml` layouts, assets in the\n`./WORKSPACE` directory, while live-viewing on `https://127.0.0.1:1990`.\n\n### ^^^ YOU EDIT IN ./WORKSPACE !!!\n\n### HOWTO Links\n\nOnly ever use the following link notation to link to other docs:\n\n```markdown\n[blah][/folder/doc]  # no extension, start with /\n[back to the root index](/)\n[some tutorial](/tutorials/foo)\n```\n\n\n### HOWTO Images\n\n**For multi-repo reasons, we never serve images from the `assets/` folder**.\nThey wouldn't show up on GitHub!\n\nInstead, we upload them into the `docs-assets/` folder of the\n[zml.github.io website repo](https://github.com/zml/zml.github.io/).\n\nUntil Zine is fixed (Loris is working on it), use the following notation for\nimages:\n\n```markdown\n[blah]($image.url('https://zml.ai/docs-assets/image.png'))\n```\n\nOnce it is fixed, normal image urls, starting with `https://` will work again.\nFrom then on, we can disable image-link-translation.\n\n\n## COMMITTING\n\nWhen you're done editing, run in the root dir of this repo:\n\n```console\nzig build tool -- commit\n```\n\nThe above will split the YAML header and content from\n`WORKSPACE/content/.../*.smd` files:\n\n- YAML will go into `.smd` files in this repo, in `content/.../*.smd`\n- Markdown content will go into `.md` files in the zml repo in\n  `zml/docs/content/.../*.md`\n\nSo you need to (add and) commit both repos:\n\n- `git commit` : this repo: `.smd`, assets, layouts\n- `git commit -C zml` : `.md` Markdown content\n\nTo help you with that, `zig build tool -- commit` will run a `git status` in\nboth repos at the end.\n\n```\nzig build tool -- commit\nContent scan took 1ms\ninfo: COMMIT in ./WORKSPACE/\ninfo: Performed Actions\ninfo: - ProcessingFile{ .filename=\"WORKSPACE/content/misc/zml_api.smd\", }\ninfo: - SplitSmd{ .source_file=\"WORKSPACE/content/misc/zml_api.smd\", .smd_dest=\"content/misc/zml_api.smd\", .md_dest=\"zml/docs/misc/zml_api.md\", }\ninfo: - ProcessingFile{ .filename=\"WORKSPACE/content/misc/style_guide.smd\", }\ninfo: - SplitSmd{ .source_file=\"WORKSPACE/content/misc/style_guide.smd\", .smd_dest=\"content/misc/style_guide.smd\", .md_dest=\"zml/docs/misc/style_guide.md\", }\n\n...\n\n\n======================================================================\nChanges in this repo:\n======================================================================\nOn branch master\nYour branch is up to date with 'origin/master'.\n\nChanges not staged for commit:\n  (use \"git add \u003cfile\u003e...\" to update what will be committed)\n  (use \"git restore \u003cfile\u003e...\" to discard changes in working directory)\n        modified:   content/misc/index.smd\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\n\n\n\n======================================================================\nChanges in zml repo:\n======================================================================\nOn branch master\nYour branch is up to date with 'origin/master'.\n\nChanges not staged for commit:\n  (use \"git add \u003cfile\u003e...\" to update what will be committed)\n  (use \"git restore \u003cfile\u003e...\" to discard changes in working directory)\n        modified:   docs/content/misc/index.md\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\n```\n\n### NOTE:\n\n- The `.smd` files are the authoritative source of existence,\n      meaning: if there is no `.smd` file in `./contents/`, its associated\n      `.md` file from the `zml` repo will not move into the workspace.\n\nYou can use above as a feature, adding `.md` files that are intended only for\nGH browsing use, even in the `content/` directory; although, I'd advise against\nsuch shenanigans.\n\n**NOTE 2:**\n\n- if you ever need to remove or rename a file in the docs:\n- you must `rm`/`mv` it in both:\n    - this repo: `./content/`\n    - and the zml repo: `./zml/docs/content/`\n\n\n## HACKING\n\n- `build.zig` : builds all prerequisites, runs `tool` or tests\n\n- `tools/tool.zig` : the main cmdline interface:\n\n```\nUsage: zig build tool -- command [opts]\n\nCommands in order:\n-1: help               : prints this help message\n 0: clone [gitref]     : clones zml and optionally checks out gitref\n 1: edit               : creates and prepares the WORKSPACE for editing\n 2: build [serve ...]  : builds the (edited) website and optionally runs the dev server\n 3: commit             : prepares the WORKSPACE for committing\n```\n\n- `tools/processor.zig` : translates between markdown and supermarkdown, called\n  from `tool` (above)\n\n- `tools/shell.zig` : little helpers do to shell scripty things\n\n- `tools/regex.zig` : PCRE2 regex search / replace helpers for Markdown link\n  replacements.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzml%2Fdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzml%2Fdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzml%2Fdocs/lists"}