{"id":15464353,"url":"https://github.com/nitya/docusaurus-demo","last_synced_at":"2026-05-06T11:31:31.457Z","repository":{"id":68197780,"uuid":"447641903","full_name":"nitya/docusaurus-demo","owner":"nitya","description":"Exploring the Docusaurus site generator features and deployment options in a demo sandbox.","archived":false,"fork":false,"pushed_at":"2022-01-23T14:06:08.000Z","size":10716,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-25T22:44:50.231Z","etag":null,"topics":["blog","documentation","docusaurus","javascript","markdown","pwa","react"],"latest_commit_sha":null,"homepage":"https://docu-demo.nitya.dev","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/nitya.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}},"created_at":"2022-01-13T15:02:25.000Z","updated_at":"2023-05-20T03:02:23.000Z","dependencies_parsed_at":"2023-03-23T01:30:49.394Z","dependency_job_id":null,"html_url":"https://github.com/nitya/docusaurus-demo","commit_stats":{"total_commits":23,"total_committers":2,"mean_commits":11.5,"dds":0.08695652173913049,"last_synced_commit":"7576cdda6c0e324e3a4443d29ceca762e8a49910"},"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/nitya/docusaurus-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitya%2Fdocusaurus-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitya%2Fdocusaurus-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitya%2Fdocusaurus-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitya%2Fdocusaurus-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nitya","download_url":"https://codeload.github.com/nitya/docusaurus-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitya%2Fdocusaurus-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32691670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["blog","documentation","docusaurus","javascript","markdown","pwa","react"],"created_at":"2024-10-02T00:34:14.862Z","updated_at":"2026-05-06T11:31:31.440Z","avatar_url":"https://github.com/nitya.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e OBJECTIVE \n\nBuild a docusaurus-powered site, deploy it to Azure Static Web Apps, automate builds with GitHub Actions - then use it to learn/test various features in the framework. Create a template that can be instantiated for other projects.\n\n\u003e STATUS\n\nCurrently built/\n\n[![Deploy to GitHub Pages](https://github.com/nitya/docusaurus-demo/actions/workflows/deploy.yml/badge.svg)](https://github.com/nitya/docusaurus-demo/actions/workflows/deploy.yml) \n\n[![pages-build-deployment](https://github.com/nitya/docusaurus-demo/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/nitya/docusaurus-demo/actions/workflows/pages/pages-build-deployment)\n\n---\n\n# DOCUSAURUS OVERVIEW\n\n## 1. What is Docusaurus\n\nDocusaurus is a framework (from Facebook/Meta) to help build single-page applications with a single focus usage: to _write and publish content_.\n\n\u003e FEATURES\n\n * Static site generator built with React. Born fast, accessible.\n * Markdown authoring, with [MDX](https://mdxjs.com/) components support \n * First-class Typescript support\n * Localization support pre-configured (70 languages)\n * Built-in versioning and search support \n * SEO friendly\n\n\u003e POPULARITY\n\n * Ranked #3 on [2021 Rising Stars in Static Sites](https://risingstars.js.org/2021/en#section-ssg) after Next, Astro.\n * Continuing upwards trend in [npm downloads](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)\n * Growing [Showcase](https://docusaurus.io/showcase) for real-world usage examples\n\n\u003e RESOURCES\n\n - read the [docs](https://docusaurus.io/docs)\n - learn the [CLI and API](https://docusaurus.io/docs/cli)\n - review [comparison with other tools](https://docusaurus.io/docs#comparison-with-other-tools) like Docsify, Gatsby, Jekyll and more. \n - try [Playground](https://docusaurus.io/docs/playground) to explore Docusaurus without installing anything. \n - fast track [Getting Started](https://docusaurus.io/docs) with docusaurus.\n\n---\n\n## 2. Docusaurus Cheatsheet\n\nQuick commands to do the key actions related to creating, building, and previewing, the site contents during development.\n\n| Command | Description |\n|:--- |:--- |\n| `npx create-docusaurus@latest \u003cwww\u003e classic` | Create new site in folder `www/` with classic theme (fast track) |\n| `cd www; npx docusaurus start` | Preview site locally (with hot reload) |\n| `cd www/src/pages; touch \u003cnewpage.md\u003e` | Creates a new standalone page that gets hosted at route: `/newpage`. Can be created as Markdown or as React component. |\n| `cd www/docs; mkdir \u003cgroup\u003e; touch \u003cgroup/page-X\u003e.md` | Creates new collection of pages at `/docs/group` consisting of all `page-X` files. Group automatically gets `Previous/Next` navigation footers and automated `Sidebar` (customizable)  |\n|`cd www/blog; touch \u003cpost.md\u003e` | Create blog post. Blogging system supports index, tags, RSS feed - withc [fronmatter](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter) for better SEO. If post name takes form `\u003cyyyy-mm-dd-slug.md\u003e`, this is automatically mapped to publication date and route path.|\n| `cd www; npm run build` | Builds static site (production files) in `build/` folder by default, ready for deployment. |\n|`cd www; npm run serve`| Test production build locally. Explore [deployment guides](https://docusaurus.io/docs/deployment) to setup workflows to push build to relevant hosting provider. |\n\n---\n\n## 3. Features To Explore\n\nSome features I hope to explore (and add tutorials on) with relevant docs links.\n\n| | |\n|:---| :---|\n| [Markdown Frontmatter](https://docusaurus.io/docs/docs-markdown-features#markdown-frontmatter) | Metadata added to top of Markdown pages that translates to HTML meta tags (good for SEO). See available options for [docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter) and [blog](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog#markdown-frontmatter). |\n| [MDX + React Components](https://docusaurus.io/docs/markdown-features/react) | Enhance Markdown with JSX syntax, allowing you to import and embed interactive content or components into pages. See [Example](https://tutorial.docusaurus.io/docs/tutorial-basics/markdown-features#mdx-and-react-components) of usage. Create [MDX Plugins](https://docusaurus.io/docs/markdown-features/plugins) for customization. |\n| [Versioning](https://docusaurus.io/docs/versioning) | Helps maintain multiple versions of content (e.g., legacy, current, upcoming) - allowing older versions to be accessible even as current versions take priority.loca Try the [Versioning Tutorial](https://tutorial.docusaurus.io/docs/tutorial-extras/manage-docs-versions/)|\n| [Localization - i8n](https://docusaurus.io/docs/i18n/introduction)| Setup content to support translations (with language-specific drop-down). Learn [translation workflow](https://docusaurus.io/docs/i18n/introduction#translation-workflow) and try to [translate your site](https://tutorial.docusaurus.io/docs/tutorial-extras/translate-your-site/) in this first tutorial.|\n| [SEO - Search Engine Optimization](https://docusaurus.io/docs/seo) | Explore best practices to improve SEO including global meta attributes, page-specific meta attributes, robots file, rich text, structured content, sitemaps and more.|\n| [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) | Enhanced syntax to support [remark](https://github.com/elviswolcott/remark-admonitions) callouts in content (note, tip, info, caution, danger) - can be used with Markdown, [MDX](https://docusaurus.io/docs/markdown-features/admonitions#admonitions-with-mdx) or [JSX](https://docusaurus.io/docs/markdown-features/admonitions#usage-in-jsx).|\n| [Tabs](https://docusaurus.io/docs/markdown-features/tabs)| Enhanced Markdown feature \u003e Tabbed Panes.|\n| [Code Blocks](https://docusaurus.io/docs/markdown-features/code-blocks) | Enhanced Markdown feature \u003e Code Highlighting .|\n| [Inline TOC](https://docusaurus.io/docs/markdown-features/inline-toc) | Enhanced Markdown feature \u003e Table Of Contents |\n| [Assets](https://docusaurus.io/docs/markdown-features/assets) | Enhanced Markdown feature \u003e Inline SVG, Themed Images, Files, etc.|\n| [Math](https://docusaurus.io/docs/markdown-features/math-equations) | Enhanced Markdown feature \u003e Math Equations.|\n| [Head](https://docusaurus.io/docs/markdown-features/head-metadata) | Enhanced Markdown feature \u003e Automatic and extensible `\u003chead\u003e` metadata|\n\n---\n\n# DEPLOYMENT OPTIONS\n\n\n## 1. Deploy to GitHub Pages\n\nLet's explore [this tutorial](https://docusaurus.io/docs/deployment#deploying-to-github-pages) to see how we can deploy this site to the GitHub Pages endpoint on this repo.\n\n| Step | Description |\n|:---|:---|\n| 1. [Modify docusaurus.config.js](https://docusaurus.io/docs/deployment#docusaurusconfigjs-settings)  | Add `organizationName`=user, `projectName`=repo, `deploymentBranch`=gh-pages properties. \u003cbr/\u003eUpdated `url` property to relevant github.io version for now |\n| 2. [Configure publishing source for GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)| Use the _Pages_ Settings to setup a default `gh-pages` branch. This publishes the page to [https://nitya.github.io/docusaurus-demo/](https://nitya.github.io/docusaurus-demo/) |\n| 3. [Setup GitHub Actions for auto-deploy](https://docusaurus.io/docs/deployment#triggering-deployment-with-github-actions) | We want this to auto-deploy build to gh-pages when new commit is made to `main/`. Follow the directions for \"Same\" repo - add `deploy.yml` and `test-deploy.yml` to `.github/workflows` -- commit changes! I used `www/**` for paths) and `npm` for build)  |\n| 4. [Visit Actions Dashboard](https://github.com/nitya/docusaurus-demo/actions) | Commits should trigger action - verify that build/deploy works. |\n| 5. [Add CNAME for Custom Domain](https://docusaurus.io/docs/deployment#github-pages-overview) | Create `CNAME` file in static directory - move configuration back to `baseUrl:'/'` and set `url` to custom domain. Note that you need to [configure DNS](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) on your domain provider site. Don't forget to \"Enable HTTPS\" in Pages settings. May need to wait a while before domain is activated!|\n---\n\n## 2. Deploy to Azure Static Web Apps\n\nLearn more about [Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/publish-gatsby) then explore tutorials like [this one](https://dev.to/sumitkharche/deploy-a-docusaurus-app-on-azure-static-web-apps-2dpj). I'll update this section with a detailed tutorial based on my workflow when done.\n\n\u003e TODO\n\n| | |\n|:---|:---|\n| | |\n\n---\n\n# CONTENT CREATION\n\nI'll capture any notes/a-ha moments from my exploration here.\n\n\n## 1. [Customize Styling](https://docusaurus.io/docs/styling-layout#global-styles)\n\n\u003e Use the [recommended tool](https://docusaurus.io/docs/styling-layout#styling-your-site-with-infima) to generate a color palette that works for dark/light modes etc. Use [Themed Images](https://docusaurus.io/docs/markdown-features/assets#themed-images) to provide alternate versions of images suitable for dark/light themes. |\n\nIn the last step for instance, you can generate CSS styles for dark and light modes that are optimized for contrast etc. as seen below. \n\n| | |\n|:---| :---|\n| ![Dark Palette Example](static/dark-palette.png) | ![Light Palette Example](static/light-palette.png) |\n\nThis gives you nice themed pages for your site! \n\n| | |\n|:---| :---|\n| ![Dino-Might Dark](static/dinomight-dark.png) | ![Dino-Might Light](static/dinomight-light.png) |\n\nTODO: Try ThemedImages to match dark/light mode.\n\n\u003e REFACTORING DEFAULT SITE\n\nBefore diving into PWA refactoring, let's get the base content in order. Specifically:\n * Clean up unused files\n * Create (or clean up) sample blog post\n * Create (or clean up) sample document\n\nThere are three kinds of content to work with: Pages (standalone), Documents (collections) and Blogs (timestamped posts). Customization happens in 2 ways:\n * configuration at `docusaurus.config.js`\n * configuration via Markdown frontmatter in page.\n\nWe'll look at these next.\n\n---\n\n## 2. [Work with Pages](https://docusaurus.io/docs/creat.ing-pages)\n\nThings to know:\n * These are _standalone_ pages e.g., an \"About\" page for site.\n * Pages can be created as _Markdown (.md) or React (.js)_.\n * Pages are then _accessible at routes mapped to that path_ e.g.\n    - /src/pages/index.js → [baseUrl]\n    - /src/pages/foo.js → [baseUrl]/foo\n    - /src/pages/foo/test.js → [baseUrl]/foo/test\n    - /src/pages/foo/index.js → [baseUrl]/foo/\n\n---\n\n## 3. [Work with Docs](https://docusaurus.io/docs/docs-introduction)\n\nThings to know:\n * These organize pages into \"collections\" with a hierarchy.\n * Hierarchy drives automatic navigational cues (Previous/Next)\n * Sidebar provides automatic (and explicitly customizable) listings\n * Docs have default unique `id` (filename) that maps to their route\n * You can customize id (+ other properties) in [docs frontmatter](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter).\n * You can [reference other docs](https://docusaurus.io/docs/docs-markdown-features) intuitively.\n * Customize sidebar [for docs](https://docusaurus.io/docs/sidebar) using frontmatter (local) or `sidebar.js` (global).\n * Customize sidebar [for categories](https://docusaurus.io/docs/sidebar#autogenerated-sidebar-metadata) further in `_category_.json` local files.\n * Make sidebar [hideable](https://docusaurus.io/docs/sidebar#hideable-sidebar) in `docusaurus.config.js` (in _themeConfig_)\n * Understand sidebar [association](https://docusaurus.io/docs/sidebar#using-multiple-sidebars) if listing page in multiple sidebars.\n * Explore [versioning](https://docusaurus.io/docs/versioning) to evolve docs while keeping legacy accessible.\n * Check out this [complex example](https://docusaurus.io/docs/sidebar#complex-sidebars-example) to see all customizability options.\n\n---\n\n## 4. [Work with Blogs](https://docusaurus.io/docs/blog)\n\nThings to know:\n * Add [new blog posts](https://docusaurus.io/docs/blog) in `blog/` folder\n * Use `\u003c!--truncate--\u003e` [in your post](https://docusaurus.io/docs/blog#blog-list) to mark cutoff for index summary.\n * Edit [`docusaurus.config.js`](https://docusaurus.io/docs/blog#blog-sidebar) to config pagination, sidebar, reading time etc.\n * Use [`authors.yml`](https://docusaurus.io/docs/blog#global-authors) to define global authors, reference in frontmatter.\n * Configure [feed](https://docusaurus.io/docs/blog#feed) or disable it, via `docusaurus.config.js`.\n\n---\n\n# ADVANCED CONCEPTS\n\n## 1. Progressive Web Apps\n\n[Progressive Web App](https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/) are about leveraging new capabilities in web browser APIs and standards to drive richer user experiences - implementing a _progressive enhancement_ approach that continues to deliver functional and valid experiences on older platforms that lack these features.\n\nWith PWA, you get the reach of web apps with the richer experience of platform (native) apps. Making a web app a PWA requires us to focus on three things:\n * _Reliability_ = does it work offline like native apps do?\n * _Installability_ = can it be launched from home screens like native apps?\n * _Capability_ = can it leverage rich platform APIs like native apps do?\n\n### 1.1 [Run a Lighthouse Audit](https://developers.google.com/web/tools/lighthouse/)\n\nLighthouse is an open-source tool for improving quality of web pages by auditing it for _performance, accessibility, PWA, SEO, and more_. The easiest way is to [run it in DevTools](https://developers.google.com/web/tools/lighthouse/#devtools) (in a Chromium-powered browser like Google Chrome, Microsoft Edge or Brave) and review the generated report. Here is the result for my initial [deployed site](https://docu-demo.nitya.dev)\n\n| | |\n|:---| :---|\n| ![Lighthouse Report Overall](static/lighthouse-report.png) | ![Lighthouse Report PWA](static/lighthouse-pwa.png) |\n\nThis gives you a checklist of things to fix with recommendations on how to fix them.\n\n### 1.2 [Audit with PWA Builder](https://www.pwabuilder.com/)\n\nFor the PWA part, you can go one step better and run a  [PWABuilder Audit](https://blog.pwabuilder.com/posts/introducing-the-brand-new-pwa-builder/) - it also gives you a score, and has a nice web interface where you can interactively configure options to _generate_ the fixes required to improve it.\n\nPlus - if you want to _ship_ your PWA to an app store (Microsoft - Windows, Google Play - Android, Apple - iOS) as well, the site has resources to guide you through the process and ensure your PWA is store-ready.\n\n| Here is the initial PWABuilder audit report for the [deployed website](https://docu-demo.nitya.dev/). |\n|:---|\n| ![PWA Builder Audit](static/pwabuilder-audit.png) |\n| Looks like we need to put in a bit of work - starting with adding a Manifest and Service Worker, then iteratively auditing for performance and other optmizations. The report does provide us assistance in creating the required files interactively. |\n\n\n### 1.3 Fix it with plugin-pwa\n\nDocusaurus has a [plugin-pwa](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa) to create a website with both offline and installation support.\nLet's use this - then run the audit again to see what changes in scoring.\n\n\u003e 1. CREATE \u0026 LINK APP MANIFEST\n\nLearn about [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) here. \n\nPWABuilder lets you create icons, screenshots and manifest interactively - so I used it.\n\n  * Icons - Download the generated icons and save to a location inside `www/static`. I've saved mine in `static/img/icons`.\n  * Screenshots - Download the mobile and desktop versions of screenshots for specific routes of interest, and save as before. I've saved mine in `static/img/screenshots`.\n  * Manifest - Fill in the details interactively in the form. Generate manifest and save the file to `static/manifest.json`. This is what you get initially.\n \n ```\n {\n    \"background_color\": \"none\",\n    \"description\": \"A sandbox app to explore various features of the Docusaurus static site builder. Use as a template for other projects, or browse the tutorials section to build  this from scratch.\",\n    \"dir\": \"ltr\",\n    \"display\": \"standalone\",\n    \"name\": \"Docusaurus Demo\",\n    \"orientation\": \"portrait-primary\",\n    \"scope\": \"/\",\n    \"short_name\": \"Docu-Demo\",\n    \"start_url\": \"/\",\n    \"theme_color\": \"#af0404\",\n    \"categories\": [],\n    \"screenshots\": [],\n    \"shortcuts\": []\n  }\n ```\n\n * Update the manifest to provide locations for the downloaded screenshots and icons. Reference the [screenshot example](https://developer.mozilla.org/en-US/docs/Web/Manifest/screenshots) and [icons example](https://developer.mozilla.org/en-US/docs/Web/Manifest/icons) to learn what to add. \n \n Here is what my additions looks like - note that relative paths are w.r.t location of `manifest.json`. Note - for now the `icons/` directory contains all sizes generated by PWABuilder - but at some point we can remove all the ones that are not listed in the Manifest (for efficiency).\n \n ```\n \"screenshots\" : [\n  {\n    \"src\": \"img/screenshots/home-desktop\",\n    \"sizes\": \"1280x800\",\n    \"platform\": \"wide\",\n    \"label\": \"Homescreen of Docusaurus Demo PWA\"\n  },\n  {\n    \"src\": \"img/screenshots/home-mobile\",\n    \"sizes\": \"750x1334\",\n    \"platform\": \"narrow\",\n    \"label\": \"Homescreen of Docusaurus Demo PWA\"\n  },\n  {\n    \"src\": \"img/screenshots/blog-desktop\",\n    \"sizes\": \"1280x800\",\n    \"platform\": \"wide\",\n    \"label\": \"Blog page of Docusaurus Demo PWA\"\n  },\n  {\n    \"src\": \"img/screenshots/blog-mobile\",\n    \"sizes\": \"750x1334\",\n    \"platform\": \"narrow\",\n    \"label\": \"Blog page of Docusaurus Demo PWA\"\n  },\n],\n\"icons\": [\n    {\n      \"src\": \"img/icons/icon-72x72.png\",\n      \"sizes\": \"72x72\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-96x96.png\",\n      \"sizes\": \"96x96\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-128x128.png\",\n      \"sizes\": \"128x128\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-144x144.png\",\n      \"sizes\": \"144x144\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-152x152.png\",\n      \"sizes\": \"152x152\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-192x192.png\",\n      \"sizes\": \"192x192\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-388x388.png\",\n      \"sizes\": \"388x388\",\n      \"type\": \"image/png\"\n    },\n    {\n      \"src\": \"img/icons/icon-512x512.png\",\n      \"sizes\": \"512x512\",\n      \"type\": \"image/png\"\n    }\n]\n ```\n \n * This is also a good time to update the `static/img/favicon.ico` with an icon that matches your brand. I used the [favicon converter](https://favicon.io/favicon-converter/) site to generate a favicon from one of the icon images.\n\n\n\u003e 2. CONFIGURE THE PLUGIN\n\nDocusaurus [plugin-pwa](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa) is configured as follows:\n\n * Install the plugin: `$cd www; npm install --save @docusaurus/plugin-pwa` \n * Requires Manifest to be in `static/manifest.json`. See an [example manifest](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#manifest-example) for reference.\n * Requires `docusaurus.config.js` to be updated to configure plugin - see [example](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#configuration) and [supported options](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#options).\n\nThis configures your app to use the referenced manifest (to set as `\u003cHEAD\u003e` link) and set the relevant policies (for service worker).\n\n\u003e 3. TEST PWA\n\nHow can you check if the PWA functionality is working correctly, and if there are ways to improve it.\n\n\u003e 1. TEST APP LOCALLY\n\nThe plugin activates only for production builds. So clear-build-and-serve on `https://localhost:3000` to run locally.\n\n```\n$ cd www/\n$ npm run clear\n$ npm run build\n$ npm run serve\n```\n\nThen _inspect_ the webpage - e.g., in a Chromium-powered browser (e.g., Microsoft Edge or Google Chrome) - and look for the _Applications_ tab. \n|Check out the Manifest section - it should let you know of any issues to be addressed.| Check out the Service Workers section. It should show a registered worker.|\n|:---|:---|\n|![Screenshot of inspected localhost PWA (Manifest)](static/localhost-inspect.png)|![Screenshot of inspected localhost PWA (Manifest](static/localhost-sw.png)|\n\nIf you can see something similar, it tells you that the pwa-plugin is configured correctly. Now all we have to do is start fixing the issues. \n\n\n\u003e 2. RUN PWA AUDITS\n\nFirst, let's re-run audits so we can get a list of all issue at one shot, before starting fixes. First, push the deploy to remote host so it is publicly accessible.\n\n`LIGHTHOUSE AUDIT`:\n\nVisit [the deployed page](https://docu-demo.nitya.dev) in a Chromium-powered browser (Google Chrome, Microsoft Edge, Brave etc.). Then `inspect` the page and click `Generate Report` in the Lighthouse tab.Run it for the default `mobile` option, then repeat with `desktop` to audit page performance for both narrow-screen and wide-screen device form factors. _Yes!! Our scores have improved!_.\n\n| | |\n|:---| :---|\n|Lighthouse Report - Mobile  |  Lighthouse Report - Desktop. |\n| ![Lighthouse Report - Mobile](static/lighthouse-mobile.png) | ![Lighthouse Report - Desktop](static/lighthouse-desktop.png) |\n\n\n`PWABUILDER AUDIT`:\n\nVisit the [PWA Builder](https://www.pwabuilder.com) site and enter your [site URL](https://docu-demo.nitya.dev) for auditing. Here's my new report - along with some guidance on improvements to make it appstore-ready.\n\n| | |\n|:---| :---|\n| **PWABuilder Report** - _note how our scores have improved dramatically from 30 to 160!_ |  **PWA Builder Alert** - _provides [actionable advice](https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/how-to/icon-theme-color#define-icons) to make PWA appstore-ready_. |\n| ![PWABuilder Report](static/pwabuilder-report.png) | ![PWABuilder Alert](static/pwabuilder-alert.png) |\n\n\n\u003e 3. TEST PWA CAPABILITIES\n\nWe have a PWA-enabled site deployed! Let's test it for two key features that differentiate PWA from regular web apps:\n\n * [App Installation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#app-installation-support) - can I install this to home screen and use it like a native app?\n * [Offline Mode (Precaching)](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#offline-mode-precaching) - does the site remain accessible when I am offline?\n\n Let's look at each of these.\n\n \u003e 1. APP INSTALLATION\n\n Can I install this app on my home screen (e.g., on mobile) and have it be accessible on my dock (e.g., desktop) and via other means (e.g., Search) just like native apps? \n \n Let's try it out. See guidance on [How to install and uninstall apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Installing) on various mobile and desktop browsers. Also see: [App Installation | Docusaurus](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#app-installation-support)\n \n \n\n| | **Here is what my experience with Microsoft Edge (browser) on a macOS laptop (device) looks like.** |\n|:---|:---|\n| Tap the `...` on Edge browsers, navigate to `Apps \u003e Install This Site As An App` to trigger install. | ![Microsoft Edge App Install Flow](static/edge-app-install.png) |\n| This is the installed _standalone_ app experience. \u003cbr/\u003e Notice the lack of browser chrome (no address bar) - and alert indicating new version available. | ![Edge-installed App in standalone mode](static/edge-app-standalone.png) |\n| And this is my dock on macOS - note how I can pink this to dock and launch instantly, just like native.| ![PWABuilder Repo`rt](static/edge-app-macos.png) |\n\n\n \u003e 2. OFFLINE MODE\n\nA big advantage of platform-specific (native) apps is their ability to function even when the device is offline. Can we get the same kind of reliable offline access in PWA? That's what service workers do for us.\n\nLet's try it out. Install the app using the browser-appropriate actions. For example:\n * in mobile Chrome: click \"...\" then select `Add To Home Screen`\n * in mobile Edge: click \"...\" then select `Add To Phone`.\n\nIn either case, you should now see a launcher icon on your home screen, its name corresponding to that given in your manifest. \n * On my Android phone, I also see a subtle browser icon (Edge or Chrome) inside the launcher icon, to let me know which browser PWA was installed from.\n * I have different browsers associated with different profiles (Personal vs. Work) on my Android Phone. And, just like other native apps, the installed PWA launcher icon is enabled only when the relevant profile is active.\n\nNow, put your phone into `Flight mode` (effectively offline).\n * Launch a standard browser now and go to your [site link](https://docu-demo.nitya.dev), you should get the dreaded `No internet` page indicating the device is offline.\n * Now try launching the installed PWA from home screen. It should launch _and_ allow you to navigate to other links (e.g., visit Home, Blog and Tutorial pages). \n\nAn installable and offline-ready PWA ftw! Also see: [Offline Mode (Precaching)](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-pwa#offline-mode-precaching)\n\n\u003e 3. FIXING AUDIT-IDENTIFIED ISSUES\n\nWe now have a working PWA but the audit identifies a number of issues we can fix. Let's do that next - for now we don't need to fix _everything_ - for example, we can wait to learn more about service worker caching strategies before exploring some of those fixes. But we can fix simpler things like manifest updates. Next.\n\n\n---\n\n## 2. End-to-End Testing\n\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitya%2Fdocusaurus-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitya%2Fdocusaurus-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitya%2Fdocusaurus-demo/lists"}