{"id":13425191,"url":"https://github.com/amirmasoudabdol/preferably","last_synced_at":"2025-04-15T21:48:16.500Z","repository":{"id":45653667,"uuid":"321673541","full_name":"amirmasoudabdol/preferably","owner":"amirmasoudabdol","description":"An accessible template for `pkgdown` websites with dynamic light/dark mode support","archived":false,"fork":false,"pushed_at":"2024-07-26T09:28:06.000Z","size":11499,"stargazers_count":61,"open_issues_count":5,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-15T21:48:09.907Z","etag":null,"topics":["bootstrap3","bootstrap5","documentation","pkgdown","rstats","static-site-generator","template","theme"],"latest_commit_sha":null,"homepage":"https://preferably.amirmasoudabdol.name","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amirmasoudabdol.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2020-12-15T13:18:22.000Z","updated_at":"2025-03-22T10:35:45.000Z","dependencies_parsed_at":"2024-09-23T11:01:03.884Z","dependency_job_id":"cda56729-8dbb-4e7c-b5d8-ab6ae64eccde","html_url":"https://github.com/amirmasoudabdol/preferably","commit_stats":{"total_commits":128,"total_committers":6,"mean_commits":"21.333333333333332","dds":0.0546875,"last_synced_commit":"296b4afa914be3a5b91184bbad461eb3fe15548c"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirmasoudabdol%2Fpreferably","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirmasoudabdol%2Fpreferably/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirmasoudabdol%2Fpreferably/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirmasoudabdol%2Fpreferably/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amirmasoudabdol","download_url":"https://codeload.github.com/amirmasoudabdol/preferably/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249161104,"owners_count":21222468,"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":["bootstrap3","bootstrap5","documentation","pkgdown","rstats","static-site-generator","template","theme"],"created_at":"2024-07-31T00:01:06.983Z","updated_at":"2025-04-15T21:48:16.480Z","avatar_url":"https://github.com/amirmasoudabdol.png","language":"HTML","funding_links":["https://github.com/sponsors/amirmasoudabdol"],"categories":["HTML"],"sub_categories":[],"readme":"# preferably \u003cimg src=\"man/figures/logo.png\" width=\"120\" align=\"right\"/\u003e\n\n{preferably} is an **accessible** template for [pkgdown](https://pkgdown.r-lib.org/) documentation websites. It uses a [light](https://bootswatch.com/flatly/) and a [dark](https://bootswatch.com/darkly/) theme and utilizes the [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) CSS variable to *automatically* serve either of the two based on users' operating system setting, or allowing them to manually toggle between them.\n\nBesides offering light and dark mode, I spent some time making the overall reading experience of 'pkgdown' documentations just a bit nicer, by using richer fonts, adopting a better color scheme for codes, etc. \n\n![](man/figures/comparison.png)\n\n\u003e Please let me know if you happen to use my template in your project. I'd like to keep a list of websites that are using 'preferably', see here: [In the Wild](https://preferably.amirmasoudabdol.name/articles/in-the-wild.html)!\n\n## Installation\n\nYou can download the stable version from CRAN using `install.packages(\"preferably\")`, or you may download the development version from GitHub as follow:\n\n```R\ninstall.packages(\"devtools\"); library(devtools)\n\ninstall.packages(\"preferably\")\n```\n\n## Usage\n\nAfter the successful installation, if you already have your pkgdown setup ready, you only need to specify the `template` parameter as follow. Then, as before, you can build your site using `build_site()` and deploy it manually using `deploy_on_branch()`.\n\n```YAML\ntemplate:\n  package: preferably\n```\n\n##### {pkgdown} 2.0 and Bootstrap 5\n\n{preferably} 0.4 is compatible with {pkgdown} 2.0 and Bootstrap 5. In order to build your website using the Bootstrap 5, your setting should look like this:\n\n```YAML\ntemplate:\n  package: preferably\n  bootstrap: 5\n```\n\n\u003e ⚠️ Keep in mind that you should NOT use `default_assets: false` when you change the default template. 'preferably' relies on some of the 'pkgdown' assets and templates.\n\n### Integration\n\nIn the case that you are using CI systems to build and deploy your website, you need to make sure that 'preferably' is available on the environment. For [GitHub Action](https://pkgdown.r-lib.org/articles/pkgdown.html?q=github%20action#publishing), add the following line to the \"Install dependencies\" section of your `.github/workflows/pkgdown.yaml` file:\n\n```YAML\n- name: Install dependencies\n  run: |\n    # ⚠️ leave other commands intact, \n    # and add the following command to the end of the list 👇🏼\n    remotes::install_deps(dependencies = TRUE)\n    install.packages(\"pkgdown\", type = \"binary\")\n    install.packages(\"preferably\")\n```\n\nIf you are using Travis-CI, add the following line to your `.travis.yml` file:\n\n```YAML\nr_github_packages:\n  - amirmasoudabdol/preferably\n```\n\n## Customization\n\nIn addition of pkgdown customization, Preferably offers a few more options as listed here.  \n\n### Custom Analytic\n\nPreferably allows for adding a custom analytic (in addition to `ganalytics`) to your website via the `canalytic` option.\n\n```YAML\ntemplate:\n  package: preferably\n  params:\n    canalytic:\n      domain: example.com\n      src: https://example.com/tracker.js\n```\n\nSetting these command will generate the following line in the HTML:\n\n```html\n\u003cscript async defer data-domain=\"example.com\" src=\"https://example.com/tracker.js\"\u003e\u003c/script\u003e\n```\n\n\u003e `{pkgdown}` 2.0 comes with a [greater list of supported trackers](https://pkgdown.r-lib.org/reference/build_site.html?q=plausi#analytics) that you can use out of the box, including [Plausible](https://plausible.io/).\n\n### Manual Light/Dark Toggle\n\nIn addition to the automatic color scheme switching, you can add a switch to the menu bar, e.g, \u003cspan class=\"fas fa-adjust fa\"\u003e\u003c/span\u003e, to allow for manual selection between light and dark themes. This can be done by setting the `toggle` option to `manual`. \n\n```YAML\ntemplate:\n  package: preferably\n  params:\n    toggle: manual\n```\n\nUnfortunately, it is not possible to have both the automatic and manual mode at the same time. There is an user experience issue here, and it is almost impossible to deliver a seamless experience without involving the server-side, [here](https://kilianvalkhof.com/2020/design/your-dark-mode-toggle-is-broken/), and [here](https://www.joshwcomeau.com/react/dark-mode/). So, you need to choose whether you like to give your users a manual toggle, or let your website adapts to their system preference.\n\n\u003e ⚠️ In order to remove the toggle button, remove the `toggle` parameter.\n\n- - -\n\n## Misc.\n\n#### Goal\n\nThe goal of `preferably` is to improve the accessibility and readability of your documentation websites.\n\n#### Future Plan\n\nMy main focus is to keep `preferably` light and compatible with `pkgdown`. Besides, I have a short list of features that I would like to add to template files, and `pkgdown` package. For those, I prefer to prepare a few pull requests and add them to `pkgdown` instead of diverging the `preferably` from its core. Let's see when I get to them! Here is a few:\n\n- Adding support for responsive text sizing\n- Improving the appearance of argument lists\n- Minimizing the size of default pkgdown templates and assets\n\n#### Contribution\n\nIf you found any bugs, or have any suggestions, please feel free to reach out to me, either by opening an [issue](https://github.com/amirmasoudabdol/preferably/issues/) or a pull request, or dropping an email. \n\n#### Support\n\nIf you enjoy using {preferably}, please consider supporting it on [GitHub](https://github.com/sponsors/amirmasoudabdol). You can sponsor me monthly, or make a one-time donation! 🤗","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirmasoudabdol%2Fpreferably","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famirmasoudabdol%2Fpreferably","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirmasoudabdol%2Fpreferably/lists"}