{"id":19200275,"url":"https://github.com/darklang/docs","last_synced_at":"2025-04-06T11:09:14.494Z","repository":{"id":38356018,"uuid":"238580103","full_name":"darklang/docs","owner":"darklang","description":"Darklang documentation","archived":false,"fork":false,"pushed_at":"2024-10-21T13:10:03.000Z","size":62932,"stargazers_count":43,"open_issues_count":7,"forks_count":38,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-21T20:40:09.806Z","etag":null,"topics":["darklang","docs","documentation"],"latest_commit_sha":null,"homepage":"https://docs.darklang.com","language":"JavaScript","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/darklang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"darklang"}},"created_at":"2020-02-06T01:00:05.000Z","updated_at":"2024-10-21T13:07:31.000Z","dependencies_parsed_at":"2024-01-30T20:29:29.099Z","dependency_job_id":"7849be53-071f-449a-8c42-2f482295097b","html_url":"https://github.com/darklang/docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darklang%2Fdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darklang%2Fdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darklang%2Fdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darklang%2Fdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darklang","download_url":"https://codeload.github.com/darklang/docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471520,"owners_count":20944158,"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","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":["darklang","docs","documentation"],"created_at":"2024-11-09T12:31:40.047Z","updated_at":"2025-04-06T11:09:14.465Z","avatar_url":"https://github.com/darklang.png","language":"JavaScript","funding_links":["https://github.com/sponsors/darklang"],"categories":[],"sub_categories":[],"readme":"# ✍ Darklang Documentation\n\n[![Ceasefire Now](https://badge.techforpalestine.org/ceasefire-now)](https://techforpalestine.org/learn-more)\n\nWelcome to the source for the [Darklang](https://darklang.com) documentation.\n\nContribute your improvements as a pull request or report problems in an [issue](https://github.com/darklang/docs/issues/new/choose).\n\nView the live docs on our documentation website: [https://darklang.com/docs](https://darklang.com/docs)\n\n\u003e **(ℹ)** The Darklang docs are built using [Docusaurus](https://docusaurus.io/). If you're\ntrying to do something beyond the scope of this README, please check out their docs.\n\n## 📃 What's in this document\n\n- [Get started in 5 minutes](#-get-started-in-5-minutes)\n- [Documentation structure](#-documentation-structure)\n  - [Tutorials](#-tutorials)\n  - [How-to guides](#-how-to-guides)\n  - [Explanations](#-explanations)\n  - [Reference material](#-reference-material)\n- [Project structure](#-project-structure)\n  - [Directory structure](#-directory-structure)\n- [Editing content](#-editing-content)\n  - [Editing an existing docs page](#-editing-an-existing-docs-page)\n- [Adding content](#-adding-content)\n  - [Adding a new docs page to an existing sidebar](#-adding-a-new-docs-page-to-an-existing-sidebar)\n  - [Adding items to your site's top navigation bar](#-adding-items-to-your-sites-top-navigation-bar)\n  - [Checking formatting](#-checking-formatting)\n- [How CI auto-deploys](#%EF%B8%8F-how-ci-auto-deploys)\n- [Publishing changes manually](#-publishing-changes-manually)\n\n## 🚀 Get started in 5 minutes\n\nTo change these docs and test the results locally:\n\n```sh\nnpm install\nnpm run-script start\n```\n\n## 📚 Documentation structure\n\nDarklang's documentation is organized into four categories:\n\n- Tutorials\n- How-to guides\n- Background information and discussion\n- Reference material\n\nThis follows the [Divio Documentation System](https://documentation.divio.com/).\nUsing this system, documentation in each category should not do the work of any\nother category. For example, a tutorial should just step the user through doing\nthe work, and should not provide background explanations or other reference\nmaterial, or discussion.\n\nIn the future, we intend to provide access to all this material in the app, with\ncontext-sensitive reference materials available for all product and language\nfeatures, as well as interactive tutorials and how-to guides built-in.\n\n### 🔵 Tutorials\n\nA tutorial that teaches a child how to cook:\n\n- Tells them what to do.\n- Does not explain why they are doing it.\n- Includes specifics and lets them learn the generalities over time.\n- Assumes that \"obvious\" things are not known.\n- Does not include choices.\n- Should be bulletproof.\n\n### 🔵 How-to guides\n\n- \"Recipes\" showing how to do something.\n- Should have very specific names, such as \"How to add a custom domain to Darklang.\"\n\n### 🔵 Explanations\n\n- Background material to understand further.\n- Provides context.\n\n### 🔵 Reference material\n\n- Just descriptions.\n- Follows the structure of the project/language (e.g., each type is represented).\n\n## 🗃 Project structure\n\nThere are two important branches:\n\n- `main`\n- `gh-pages`\n\nThe website is hosted on `gh-pages`, but everything there is auto-generated\nfrom `main`. When we want to make changes, we create a new branch from `main`\nin the format `username/my-change` and make as many commits as we need to.\nThen, we create a new pull request from that branch with `main` as the base.\nWhen the pull request is merged, CircleCI will automatically deploy the changes\nfrom `main` to the website (it runs a script against the source files on `main`\nand deploys the generated website to `gh-pages`).\n\n### 🔵 Directory structure\n\nThe project file structure in `main` is:\n\n```text\ndocs/\n  README.md (this file)\n\n  .circleci/config.yml (used to auto-deploy via CircleCI)\n\n  .gitignore (ignores autogenerated files that shouldn't sync via git)\n\n  .spelling (a place to add words not in a standard dictionary)\n\n  docs/ (individual markdown documentation pages)\n    changelog.md\n    getting-started.md\n    ...\n\n  src/\n    css/\n    plugins/ (docusaurus plugins)\n\n  package.json (helper scripts)\n\n  docusaurus.config.js (core site configuration)\n\n  sidebars.json (sidebar sections and pages)\n\n  static/\n    img/ (static images, posts, and also favicon.ico)\n    slack-apps/\n    tutorials/\n    index.html\n    CNAME\n    .nojekyll\n\n  node_modules/\n```\n\n## 📝 Editing content\n\nEditing content in Docusaurus is straightforward. Whether you want to make small tweaks or\nsignificant changes, the following section will guide you through the process.\n\n### 🔵 Editing an existing docs page\n\nEdit docs by navigating to `docs/` and editing the corresponding document:\n\n`docs/doc-to-be-edited.md`\n\n```markdown\n---\nid: page-needs-edit\ntitle: This Doc Needs to Be Edited\n---\n\nEdit me...\n```\n\nFor more information about working with docs, read the [Docusaurus docs](https://docusaurus.io/docs/en/navigation).\n\n## 📝 Adding content\n\nThe following section will walk you through the process of adding a new document\nand integrating it into an existing sidebar.\n\n### 🔵 Adding a new docs page to an existing sidebar\n\n1. Create the doc as a new markdown file in `/docs`. For example, `docs/newly-created-doc.md`:\n\n```md\n---\nid: newly-created-doc\ntitle: This Doc Needs to Be Created\n---\n\nMy new content here...\n```\n\n2. Refer to that doc's ID in an existing sidebar in `sidebars.json`:\n\n```javascript\n// Add newly-created-doc to the Getting Started category of docs\n{\n  \"docs\": {\n    \"Getting Started\": [\n      \"quick-start\",\n      \"newly-created-doc\" // new doc here\n    ],\n    ...\n  },\n  ...\n}\n```\n\nFor more information about adding new docs, see the guide on\n[adding items to the sidebar](https://docusaurus.io/docs/sidebar/items).\n\n### 🔵 Adding items to your site's top navigation bar\n\n1. Add links to docs, custom pages, or external links by editing the navbar items in the `themeConfig`\nsection of `docusaurus.config.js`:\n\n```javascript\n{\n  themeConfig: {\n    navBar: {\n      items: [\n        {\n          to: \"/introduction\", // The URL path to the landing page, \n          label: \"Classic\",\n          position: \"right\",\n        },\n        {\n          to: \"/next/introduction\",\n          activeBasePath: \"docs\",\n          label: \"Next\",\n          position: \"right\",\n        },  \n        {\n          href: 'https://github.com/darklang/docs',\n          label: 'GitHub',\n          position: 'right',\n        },\n        ...\n      ]\n    }\n  }\n  ...\n}\n```\n\nFor more information about the navigation bar, see the corresponding\n[Docusaurus guide](https://docusaurus.io/docs/2.x/api/themes/configuration#navbar-link).\n\n## 🔵 Checking formatting\n\nWe run some tools to ensure that the docs are consistently formatted and to find\ncommon errors. If you run `npm run format`, you should pass the linter.\n\nCI automatically runs `markdownlint`. You can run it locally as\n`npm run lint`.\n\n## ⚙️ How CI auto-deploys\n\nThe `.circleci/config.yml` file describes the CircleCI configuration. It monitors commits\nand merges into the `main` branch, runs a script to generate the contents of `gh-pages`,\nand pushes `gh-pages` to GitHub.\n\n## 🔧 Publishing changes manually\n\n\u003e **(ℹ)** You shouldn't need to do this because CircleCI runs this\nautomatically.\n\nOn the command line (remember to replace `\u003cYOUR USERNAME\u003e` with your GitHub\nusername):\n\n```sh\nGIT_USER=\u003cYOUR USERNAME\u003e CURRENT_BRANCH=main npm deploy\n```\n\nIf you're using SSH instead of HTTPS, replace `GIT_USER=\u003cYOUR USERNAME\u003e` with\n`USE_SSH=true`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarklang%2Fdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarklang%2Fdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarklang%2Fdocs/lists"}