{"id":17979989,"url":"https://github.com/peckjon/github-to-guru","last_synced_at":"2025-03-25T17:33:07.180Z","repository":{"id":38285312,"uuid":"257354102","full_name":"peckjon/github-to-guru","owner":"peckjon","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-18T01:37:38.000Z","size":4916,"stargazers_count":14,"open_issues_count":7,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-18T17:11:10.913Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peckjon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"peckjon"}},"created_at":"2020-04-20T17:22:53.000Z","updated_at":"2024-06-18T01:37:41.000Z","dependencies_parsed_at":"2024-06-11T01:34:55.258Z","dependency_job_id":null,"html_url":"https://github.com/peckjon/github-to-guru","commit_stats":{"total_commits":122,"total_committers":3,"mean_commits":"40.666666666666664","dds":0.06557377049180324,"last_synced_commit":"4efc3dc56154d08ad598ffee7fec5a295ed6dfa7"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peckjon%2Fgithub-to-guru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peckjon%2Fgithub-to-guru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peckjon%2Fgithub-to-guru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peckjon%2Fgithub-to-guru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peckjon","download_url":"https://codeload.github.com/peckjon/github-to-guru/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222089956,"owners_count":16929285,"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":[],"created_at":"2024-10-29T17:40:43.249Z","updated_at":"2024-10-29T17:40:43.746Z","avatar_url":"https://github.com/peckjon.png","language":"Python","funding_links":["https://github.com/sponsors/peckjon"],"categories":[],"sub_categories":[],"readme":"# GitHub to Guru\n\n**Deploy content from your GitHub repo into a Guru collection.**\n\n\u003e [!NOTE]\n\u003e This Action takes content _from_ a GitHub repo and places it _into_ a Guru collection. If you're looking to do the reverse (take a Guru collection and export it to GitHub), check out [parkerbxyz/guru-to-github](https://github.com/marketplace/actions/guru-to-github)\n\nFor standard collections, this action can add cards based on markdown files in your repository.\n\nFor [synchronized collections](https://help.getguru.com/articles/T8eX5e5c/Knowledge-Sync-Overview), it can add and replace cards, boards, board groups, and resources (see [appendix](#appendix-creating-a-synchronized-collection) for details).\n\nConfiguration can be performed by adding one YAML file per markdown file, or by adding a single `cards.yaml` file (minimal impact to your existing repo structure).\n\nSince this is an action, you can build other logic on top, such as splitting up a single markdown file into many Guru cards.\n\n![screenshot](resources/github_to_guru.png)\n\n## Example usage\n\n1. Add a Secret named `GURU_USER_TOKEN` containing a [User Token for Guru](https://help.getguru.com/en/articles/4740119-how-to-obtain-your-api-credentials)\n\n2. Add a Secret named `GURU_USER_EMAIL` containing the email address for which you [created the User Token](https://app.getguru.com/settings/api-access)\n\n3. Add a workflow file:\n\n```yaml\nname: Create guru cards\n\non:\n  push:\n    branches:\n      - master\n\njobs:\n  guru:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v1\n    - uses: peckjon/github-to-guru@master\n      env:\n        GURU_USER_EMAIL:  '${{ secrets.GURU_USER_EMAIL }}'\n        GURU_USER_TOKEN:  '${{ secrets.GURU_USER_TOKEN }}'\n        GURU_COLLECTION_ID: '********-****-****-****-************'\n        GURU_CARD_FOOTER: 'To edit this card, visit https://github.com/${{ github.repository }}'\n```\n\nSet GURU_COLLECTION_ID to the `id` of the collection you wish to update (you can get it from the [collections API](https://api.getguru.com/api/v1/collections)). \n\n_**IMPORTANT NOTE:** If you are planning on creating a synchronized collection, you must first create the collection via the API (See Appendix on how to do this), and then retrieve the id from the response._\n\nGURU_CARD_FOOTER is optional; if used, it will add this text to the end of each Card (separated by a line `\\n---\\n`). Any instances of `__CARDPATH__` in the footer will be replaced with path to the card relative to the repo root. A suggested footer might be `[EDIT THIS CARD](https://github.com/${{ github.repository }}/tree/master/__CARDPATH__)`.\n\nThen, add one or more of the following to the `env`:\n\n- `GURU_COLLECTION_YAML`: path to a file in your repo containing the YAML describing your collection, as specified in the ([Guru Manual Sync documentation](https://developer.getguru.com/docs/guru-sync-manual-api#root-directory))\n- `GURU_CARD_DIR`: the path, in your repo, to a directory containing the YAML and markdown files for your cards ([documentation](https://developer.getguru.com/docs/guru-sync-manual-api#cards))\n- `GURU_CARD_YAML`: path to a single .yaml file containing the details for all cards. It should contain one entry (the path to a markdown file in your repo) for each card you wish to add, followed by the ([properties](https://developer.getguru.com/docs/guru-sync-manual-api#cards)) for that individual card, as follows:\n```\nSomeFile.md: \n  Tags: \n    - \"Subject One\"\n    - \"Subject Two\"\n  Title: \"This is Some Thing\"\nSomePath/SomeOtherFile.md: \n  Tags: \n    - \"Subject One\"\n  Title: \"This is Some Other Thing\"\n```\n- `GURU_BOARD_DIR`: the path, in your repo, to a directory containing the YAML and markdown files for your boards ([documentation](https://developer.getguru.com/docs/guru-sync-manual-api#boards))\n- `GURU_BOARD_YAML`: path to a single .yaml file containing the details for all boards. It should contain one entry for each board, followed by the ([properties](https://developer.getguru.com/docs/guru-sync-manual-api#boards)) for that individual board, as follows:\n```\nBoard1:\n  Title: Board Title\n  Description: |\n    Multi line\n    Description\n  Items:\n  - ID: \"card1\"\n    Type: \"card\"\n  - Type: \"section\"\n    Title: \"My Section\"\n    Items:\n    - ID: \"card2\"\n      Type: \"card\"\n```\n- `GURU_BOARDGROUP_DIR`: the path, in your repo, to a directory containing the YAML and markdown files for your board groups ([documentation](https://developer.getguru.com/docs/guru-sync-manual-api#board-groups))\n- `GURU_BOARDGROUP_YAML`: path to a single .yaml file containing the details for all board groups. It should contain one entry for each board group, followed by the ([properties](https://developer.getguru.com/docs/guru-sync-manual-api#board-groups)) for that individual board group, as follows:\n```\nBoardGroup1:\n  Title: Board Group One\n  Description: My first board group\n  Boards:\n  - board1\nBoardGroup2:\n  Title: Board Group One\n  Description: |\n    Multi line\n    Description\n  Boards:\n  - board2\n  - board3\n```\n- `GURU_RESOURCES_DIR`: the path, in your repo, of a directory whose files should be added as [resources](https://developer.getguru.com/docs/guru-sync-manual-api#resources). All images, PDFs, etc should be placed here, and your markdown files should use _**relative**_ links to reference them. For example, if `GURU_RESOURCES_DIR: 'SomePath/Assets'`, then a markdown file inside the folder `SomePath/SomeOtherFolder` might contain:\n```\nHere is a PDF link: [somedoc.pdf](../Assets/somedoc.pdf)\nHere is a PDF embed: \u003ciframe src=\"../Assets/somedoc.pdf\"\u003e\u003c/iframe\u003e\n```\n\n**An Important Note on Board YAML files:**\n\n- The names of Cards are modified by this script: non-alphanumeric characters are replaced by underscores (`cardFilename.replace(/\\.md$/gi,'').replace(/[^a-zA-Z0-9]/gi, '_')`). The Board YAML must use these modified names as the Card IDs (with no filetype suffix). For example, you have a markdown file `someDir/my very 1st Card!.md` and want to list this card on a Board, the Board YAML should have an Item `ID: \"someDir/my_very__1_st_Card_\"`.\n\n**Sample scripts:**\n\nIf you wish to auto-generate the YAML config files, see [sample-scripts](./sample-scripts).\n\nMany thanks to @rwnfoo for her collaboration on this work!\n\n**Other Notes:**\n\n- You cannot use both the `_DIR` and the `_YAML` way of configuring the same entity type. E.g., if you set both `GURU_CARD_DIR` and `GURU_CARD_YAML`, then `GURU_CARD_DIR` will be ignored.\n- Although the ([Guru documentation](https://developer.getguru.com/docs/guru-sync-manual-api)) requires an ExternalId and ExternalUrl for most items, you can choose to omit them here for **cards** only; the action can auto-generate these properties for you.\n- \"Synchronized\" collections take a few minutes to finish; you can check their status at `https://api.getguru.com/api/v1/import/JOBID/status`, where JOBID is the \"jobId\" shown at the end of the `peckjon/github-to-guru@master` step in your workflow's execution log.\n- Guru automatically converts Markdown to HTML, but there are some [known issues](https://github.com/peckjon/github-to-guru/issues/7) with the conversion. To preconvert Markdown files using [markdown-it](https://www.npmjs.com/package/markdown-it), set the env `GURU_CONVERT_MARKDOWN` to `1` in your workflow.\n\n### Appendix: creating a synchronized collection\n\n_Important note: A synchronized collection **must** be created via the API._\n\n1. Get the ID of a User Group as per https://developer.getguru.com/reference#groups\n2. Make a POST to https://api.getguru.com/api/v1/collections with Basic Auth using your Guru email and Guru API Token:\n```\n{\n  \"name\": \"YOUR SYNCED COLLECTION NAME\",\n  \"collectionType\": \"EXTERNAL\",\n  \"description\": \"\",\n  \"color\": \"#F44336\",\n  \"publicCardsEnabled\": false,\n  \"syncVerificationEnabled\": false,\n  \"initialAdminGroupId\": \"(GROUP_ID)\"\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeckjon%2Fgithub-to-guru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeckjon%2Fgithub-to-guru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeckjon%2Fgithub-to-guru/lists"}