{"id":18950394,"url":"https://github.com/axodotdev/oranda-js","last_synced_at":"2025-04-16T00:31:42.109Z","repository":{"id":59757627,"uuid":"538402163","full_name":"axodotdev/oranda-js","owner":"axodotdev","description":"Create beautiful and simple HTML pages from your Readme.md files","archived":false,"fork":false,"pushed_at":"2022-10-17T20:47:59.000Z","size":1275,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-19T19:03:33.259Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://axodotdev.github.io/oranda/","language":"JavaScript","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/axodotdev.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-19T08:23:09.000Z","updated_at":"2022-12-19T22:26:07.000Z","dependencies_parsed_at":"2023-01-20T02:51:40.311Z","dependency_job_id":null,"html_url":"https://github.com/axodotdev/oranda-js","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axodotdev%2Foranda-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axodotdev%2Foranda-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axodotdev%2Foranda-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axodotdev%2Foranda-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axodotdev","download_url":"https://codeload.github.com/axodotdev/oranda-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223690324,"owners_count":17186596,"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-11-08T13:22:48.709Z","updated_at":"2024-11-08T13:22:49.452Z","avatar_url":"https://github.com/axodotdev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐠 Oranda\n\nCreate beautiful and simple HTML pages from your Readme.md files\n\n- 🛠 No config\n- 👩‍💻 Code Highlighting\n- 💯 Emoji Support\n- ✨ Creates Static files\n- 🌎 OS Detection\n- 🏳️‍🌈 Pretty Pages\n- 🦄 Customizable\n- 🖼 Image minification\n- 🧠 Custom Meta Tags\n- 🇳🇱 [CodeSandbox](https://codesandbox.io) and iframe Support\n\n```bash\nyarn add oranda --dev\n```\n\n```bash\nnpm install oranda --save-dev\n```\n\n## Usage\n\n```json\n{\n  ...\n  \"scripts\": {\n    \"build:demo\": \"oranda\",\n    ....\n  }\n```\n\n## Usage with npx\n\nIf you just want a quick fancy HTML page from the Readme but don't care about running this in continuous deployment you can also use `npx` to run it as a one time thing.\n\n```bash\nnpx oranda\n```\n\nBy running this in the root folder you will also get a public folder\n\n## Options\n\nOptions can be placed in one of three ways:\n\n- `.oranda.config.json` placed in the root\n- `oranda` key in package.json\n- `package.metadata.oranda` section in the Cargo.toml\n\nIt can contain the following options:\n\n\u003c!-- markdownlint-disable --\u003e\n\n| Option          | Default                                        | Description                                                                                                                                                       |\n| --------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| file            | `Readme.md`, `readme.md`, or `README.md`       | Your Readme.md name                                                                                                                                               |\n| name            | name in `package.json`/`Cargo.toml`            | The project name that is in the title and the header                                                                                                              |\n| logo            | `''`                                           | The project logo that is in the header                                                                                                                            |\n| shareCard       | `''`                                           | URL to social media preview image for meta tags (recommended size: 1200x628, URL cannot be relative)                                                              |\n| description     | description in `package.json`/`Cargo.toml`     | The project description for meta tags                                                                                                                             |\n| homepage        | homepage in `package.json`/`Cargo.toml`        | The project homepage for meta tags                                                                                                                                |\n| noHeader        | `false`                                        | Show no header and just the markdown content                                                                                                                      |\n| theme           | `light`                                        | Options are `light`, `dark`and `àxo                                                                                                                               |\n| syntaxHighlight | `{ dark: 'poimandres', light: 'github-light'}` | What syntax highlight theme to use in dark and light mode. All [shikijs themes](https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes) can be used |\n| favicon         | `''`                                           | Favicon url or local path                                                                                                                                         |\n| dist            | `public`                                       | To what folder to render your HTML                                                                                                                                |\n| styles          | `{}`                                           | Styles to apply to the page. Object or path to css/scss file                                                                                                      |\n| additionalFiles | `[]`                                           | Any other pages to create. It expects an array of paths of markdown files                                                                                         |\n| repository      | repo in `package.json`/`Cargo.toml`            | Link to point the github corner                                                                                                                                   |\n| pathPrefix      | Environment var `PATH_PREFIX` or `/`           | Host your oranda files at e.g. /my-oranda-project                                                                                                                 |\n| meta            | `[]`                                           | Any extra meta tags you would like                                                                                                                                |\n| remoteStyles    | `[]`                                           | Array of any remote styles you want to include (eg: Google Fonts)                                                                                                 |\n| remoteScripts   | `[]`                                           | Array of any remote scripts you want to include (eg: Google Analytics)                                                                                            |\n| deployment      | `{}`                                           | Deployment options for github pages. Accepts all options [here](https://github.com/tschaub/gh-pages#options)                                                      |\n| downloads       | `{}`                                           | Links to download binaries or ways to install package, example below                                                                                              |\n\n\u003c!-- markdownlint-enable --\u003e\n\n### Example of downloads\n\nLet's say you have an app that can be install in several operating systems, you can create an object like so:\n\n```json\n{\n  \"downloads\": {\n    \"linux\": {\n      \"link\": \"https://my-app.com/my-app-x86_64-unknown-linux-musl.tar.gz\",\n      \"description\": \"this is my description if I want one\",\n      \"changelog\": \"https://my-app.com/changelog.md\"\n    },\n    \"windows\": {\n      \"link\": \"https://my-app.com/my-app-x86_64-pc-windows-msvc.tar.gz\"\n    },\n    \"mac\": {\n      \"link\": \"https://my-app.com/my-app-x86_64-apple-darwin.tar.gz\"\n    }\n  }\n}\n```\n\nOranda will automatically try to recognize the user OS and highlight the correct OS and highlight that option.\n\nThere is an example of it on the [CLI for Let's play retro games](https://cli.letsplayretro.games/)\n\nThis can also be used to demonstrate different package managers that one can use to install the package:\n\n```json\n{\n  \"downloads\": {\n    \"npm\": {\n      \"text\": \"npm i oranda\"\n    },\n    \"yarn\": {\n      \"text\": \"yarn add oranda\"\n    },\n    \"pnpm\": {\n      \"text\": \"pnpm install oranda\"\n    }\n  }\n}\n```\n\nAll objects accept the following keys:\n\n```json\n{\n  \"text\": \"Any text you want to show like a way to install, this will be automatically highlighted as a bash script\",\n  \"link\": \"Where can people download your package?\",\n  \"description\": \"Any description you want to show the user before downloading\",\n  \"changelog\": \"A link to your changelog\"\n}\n```\n\n### Example of styles\n\nFor styles you can either use a style object like so and that will override the\ndefault styles applied. Like so:\n\n```json\n{\n  \"styles\": {\n    \"h1\": {\n      \"color\": \"blue\",\n      \"backgroundColor\": \"red\"\n    }\n  }\n}\n```\n\nAnother option is to give the path to a local css or scss file.\nIn this case you need to override any specificity issues.\nYou can by using the `#oranda` id.\nExample:\n\n```scss\nbody {\n  background: #fff;\n}\n\n#oranda {\n  h1 {\n    text-transform: uppercase;\n  }\n}\n```\n\n## Meta Tags\n\nTo create any meta tags it uses an array system like so:\n\n```json\n  \"meta\": [\n    { \"name\": \"description\", \"content\": \"A cool page\" },\n    { \"property\": \"robots\", \"content\": \"robots.txt\" }\n  ]\n```\n\nThis will create the following HTML:\n\n```html\n\u003cmeta name=\"description\" content=\"A cool page\" /\u003e\n\u003cmeta property=\"robots\" content=\"robots.txt\" /\u003e\n```\n\nThe first key on the object can have any name and will be applied as presented, the second one must have the name of content and will work as presented above.\n\n## Images\n\nAny images linked in your markdown that are local will be minified and copied to your dist folder.\nIf some image is not found it will be ignored.\n\n## GitHub Corner\n\nThe GitHub corner comes from either the `repo` option in your `.oranda.config.json`\nor from the repository url in your `package.json`.\nIf none is present it will not be shown.\n\n## Lint\n\noranda also exports a command to let you lint all the markdown files you specified.\n\nYou can run this by using the `lint` command\n\n```json\n\"lint:md\" : \"oranda lint\"\n```\n\n## Deploy\n\noranda also exports a command to let you deploy your new site to GitHub pages\n\nYou can run this by using the `deploy` command\n\n```json\n\"deploy\" : \"oranda deploy\"\n```\n\nOptions for this can be passed in a `deployment` key in your config file.\nAll options can be found here: [https://github.com/tschaub/gh-pages#options](https://github.com/tschaub/gh-pages#options)\n\n## Acknowledgements\n\n- Logo from [OpenMoji](https://www.openmoji.org/library/emoji-E000/)\n\n## Contributors\n\n\u003c!-- markdownlint-disable --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore --\u003e\n| [\u003cimg src=\"https://avatars0.githubusercontent.com/u/1051509?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSara Vieira\u003c/b\u003e\u003c/sub\u003e](http://iamsaravieira.com)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=SaraVieira \"Code\") [🎨](#design-SaraVieira \"Design\") [🤔](#ideas-SaraVieira \"Ideas, Planning, \u0026 Feedback\") | [\u003cimg src=\"https://avatars2.githubusercontent.com/u/4772980?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBruno Scheufler\u003c/b\u003e\u003c/sub\u003e](https://brunoscheufler.com)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=BrunoScheufler \"Code\") | [\u003cimg src=\"https://avatars0.githubusercontent.com/u/1863771?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSiddharth Kshetrapal\u003c/b\u003e\u003c/sub\u003e](https://sid.studio)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=siddharthkp \"Code\") | [\u003cimg src=\"https://avatars3.githubusercontent.com/u/1479215?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJamon Holmgren\u003c/b\u003e\u003c/sub\u003e](https://jamonholmgren.com)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=jamonholmgren \"Code\") | [\u003cimg src=\"https://avatars0.githubusercontent.com/u/1695613?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eTimothy\u003c/b\u003e\u003c/sub\u003e](http://timothy.is)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=timothyis \"Code\") | [\u003cimg src=\"https://avatars2.githubusercontent.com/u/13808724?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAndrew Cherniavskii\u003c/b\u003e\u003c/sub\u003e](https://github.com/cherniavskii)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=cherniavskii \"Code\") | [\u003cimg src=\"https://avatars2.githubusercontent.com/u/16899513?v=4\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003etimkolberger\u003c/b\u003e\u003c/sub\u003e](https://github.com/TimKolberger)\u003cbr /\u003e[💻](https://github.com/axodotdev/oranda/commits?author=TimKolberger \"Code\") |\n| :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST: START - Do not remove or modify this section --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\u003c!-- markdownlint-enable --\u003e\n\n## License\n\nMIT - see [LICENSE](https://github.com/axodotdev/oranda/blob/master/LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxodotdev%2Foranda-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxodotdev%2Foranda-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxodotdev%2Foranda-js/lists"}