Style updates:
- New "core" theme serves as base for all other themes (official and third-party)
- New CSS custom properties for simplified customization of "core" theme
**Note:** List of available properties will be made available in documentation by embedding soruce CSS in docs after merge. Merge is required because embedded CSS needs to be in `main` branch. For now, see `_vars.css` and `_vars-advanced.css` for details.
- New theme "add-ons" modify core theme properties and/or add custom declarations as needed.
- New Prism.js theme support
- New configurable sidebar toggle design
- New typography defaults to system sans-serif and monospace fonts instead of relying on external web font.
- New "Core Dark" theme addon provide dark theme styles. Can optionally be applied based on operating system's light/dark setting using `@media` attribute on `<link>` element.
- New "Vue" theme addon. Closely replicated popular v4 theme while allowing for v5 enhancements.
- New CSS class names available for adding loading indicators, adding sidebar expand/collapse icons, adding sidebar group styles, clamping sidebar links to a single line with ellipses, and changing the sidebar toggle icon.
- New auto-generated gradient background for cover page (ensure gradient hue is > 50 degree apart, use OKLCH color if supported, randomize grandient angle, reduce brightness in dark mode)
- New button styles (basic, primary, secondary)
- New form element styles (text input, radio, checkbox, )
- New "callouts" (previously "important" and "tip" helpers)
- New default syntax highlighting theme (from [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/))
- New auto-generated theme color shade and tint colors
- New auto-generated monochromatic color palette
- New form element styles (fields, legend, text input, text area, checkbox, radio, toggles, and select)
- New "headerless" tables
- New `kbd` styles
- New task list style
- New merged navbar styles (consistent with sidebar nav styles)
- New search plugin styles and keyboard shortcut indicators
- Add ability restore previously focused content element after hiding sidebar
- Add "focus trap" when sidebar is visible on mobile (accessibility)
- Add ability for sidebar links to wrap by default (previous single-line w/ ellipsis display available as CSS class on `<body>` option)
- Add sidebar `page-link`, `group`, and `group-title` CSS classes to sidebar markup.
- Add reduced motion media query to set all animation/transition timings to zero
- Update Google Font imports (use new variable vs older fixed width fonts)
- Update primary/secondary button order on coverpage (primary should be first)
- Fix missing merged navbar when loading at desktop resolution then resizing to mobile
- Fix inverted open/close sidebar visibility state at desktop/mobile resolutions
- Fix overflow setting to prevent clipping of element focus ring
- Fix safe area inset margins on mobile in landscape orientation
- Fix inverted "tip" and "warn" class names
- Fix scroll padding to prevent headers from touching top edge of viewport when scrolled to
- Remove Stylus dependency (now using only PostCSS)
- Remove legacy themes "Buble", "Dark", "Dolphin", and "Pure".
Documentation updates:
- New "UI Kit" page showcasing all elements styled by Docsify
- Update "Quick Start" page template
- Update "Adding pages" page with information on how to properly create sidebar group titles and navbar drop-down menus
- Update "Themes" page with theme and class toggles
- Update "Configuration" page with deprecation warnings for `themeColor` and `topMargin`
- Move "Edit Page" link to footer
- Remove [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/) endorsement (currently not compatible with v5 and future is unknown)
Miscellaneous updates:
- New search plugin options: `insertBefore` and `insertAfter`
- Add PostCSS config file
- Update BrowserSync config (disable "ghost" mode)
- Update tests
- Fix Jest + Prettier 3 conflict
- Fix `getAndRemoveDocisfyIgnoreConfig` name type (now `Docisfy` => `Docsify`)
- Fix execution of sidebar-generating code when `hiddenSidebar` is `true`
- Remove `inBrowser` constant (SSR deprecated, so no longer needed)
* Fix “main” role
* Fix primary navigation role and aria label
* Fix secondary navigation aria label
* Fix progress bar role and aria labels
* Fix cover page role and aria label
* Fix search role
* Fix search results aria labels
* Add search results status element
* Update snapshots with new roles and aria labels
* chore: add missing Vue support for Vercel builds
* refactor: move some functions and module-level state into classes as private methods and properties to start to encapsulate Docsify
Also some small tweaks:
- move initGlobalAPI out of Docsify.js to start to encapsulate Docsify
- move ajax to utils folder
- fix some type definitions and improve content in some JSDoc comments
- use concise class field syntax
- consolidate duplicate docsify-ignore comment removal code
This handles a task in [Simplify and modernize Docsify](https://github.com/docsifyjs/docsify/issues/2104), as well as works towards [Encapsulating Docsify](https://github.com/docsifyjs/docsify/issues/2135).
* chore: add prettier code format check to our lint script, and add a prettier script for manually formatting the whole code base
* chore: update issue/pr templates
* chore: apply our format to the whole code base
---------
Co-authored-by: Koy <koy@ko8e24.top>
Co-authored-by: i544693 <369491420@qq.com>
BREAKING: In a minority of cases syntax updates may break apps running in very old browsers (such as Internet Explorer), or apps that build Docsify in a custom way with old build tools. To upgrade, build Docsify for older browsers in a custom way, or update existing build tools to handle newer syntax.
DEPRECATED: `$docsify.themeColor` is deprecated and will be eventually removed, use a `--theme-color` CSS variable in your style sheet.
BREAKING: The new project layout might break in some tooling setups.
We've added an exports field to `package.json` to specify where
statements like `import ... from 'docsify'` will import from, and left
the `main` and `unpkg` fields as-is for backwards compatibility with the
global <script> import method. Most people who use a non-module
`<script>` tag to import Docsify will not notice a difference. Anyone
else who is importing Docsify into a specilized build setup using
`import` statements has a chance of being broken, so we've marked this
as BREAKING.
* Update test environments and lint configuration
Update Jest (unit + integration) and Playwright (e2e) test environments. Includes stability improvements for e2e tests using newer, more stable methods per the Playwright docs.
- Update Jest 26 => 27
- Update Jest-related libs (babel parser)
- Update Playwright 1.8 => Playwright Test 1.18
- Update GitHub CI (action versions, job parallelization, and matrices)
- Update ESLint 5 => 8
- Update ESLint-related libs (parser, prettier, Jest, Playwright)
- Fix test failures on M1-based Macs
- Fix e2e stability issues by replacing PW $ method calls
- Fix ESLint errors
- Fix incorrect CI flag on Jest runs (-ci => --ci)
- Refactor e2e test runner from Jest to Playwright Test
- Refactor e2e test files for Playwright Test
- Refactor fix-lint script name to lint:fix for consistency
- Refactor npm scripts order for readability
- Remove unnecessary configs and libs
- Remove example image snapshots
* fix: duplicate search content when `/readme` or `/` exists in the sidebar
* Update
* add test
* Reset local storage before each e2e test
* Reset Playwright context instead of page
* Update playwright dependencies
Co-authored-by: John Hildenbiddle <john@hildenbiddle.com>
* Initial Jest+Playwright setup
* Fix eslint warnings
* Add placeholder for common options
* Fix load order of scriptURLs
* Add docsifyURL and waitForSelector options
* Add executeScript scenarios
* Enable firefox and webkit tests by default
* Prevent prettier from reformatting browsers list
* Update options and add JSDoc comments
* Initial commit
* Complete initial example tests
* Minor tweaks
* Change suite name
* Rename file
* Add npm script to run jest+playwright example test
* Clean up server properties
* Isolate e2e, integration, and unit test environments
- Setup projects for e2e, integration, and unit tests in Jest configuration
- Setup /tests/e2e/ tests for Jest+PlayWright
- Setup /tests/integration/ tests for Jest
- Setup /tests/unit/ tests for Jest
- Setup eslint for Jest and Jest+Playwright environments
- Move e2e configuration files into separate folder
- Update e2e example tests
- Update unit example tests
- Update HTML fixtures
* Update docsifyInit helper
- Add `debug` option
- Append `Markdown` suffix to markdown-related options
- Reorder options alphabetically
* Add jestPlaywright.debug() to e2e examples
* Removed need to pass page as arg to docsifyInit()
* Add VSCode debug configurations
* Change test server port from 8080 to 3001
* Clean up test names and expect() order
* Update npm scripts to ignore example tests
* Add CLI commands and resources section
* Add Jest unit test snapshot example
* Added Jest unit and e2e tests to Github workflows
* Add npm script to run Jest examples
Added for new devs who are exploring the examples, as the need for passing --testPathIgnorePatterns is not obvious. This flag is required because the example tests are excluded by default.
* Remove node 10.x and add 14.x from tests
Required for jest+playwright testitng
* Temporarily disable testPathIgnorePatterns for ci
* Temporarily remove node 14 from matrix
Cypress fails on node 14.x
* Alternate workflow setup for new test env
* Update workflow platforms and node versions
Also cleaning up naming
* Restoring original workflow names
* Remove Cypress tests
* Remove/Reset GitHub actions
* Restore/reset workflows
* Bump actions/checkout@v1 to v2
* Use playright GH action
* Update playwright GH action configuration
* Remove unnecessary steps and update checkout version
* Add install step
* Add --ignore-scripts flag
Linting does not require running scripts automatically executred after install.
* Swicth from ci to i for install
* Add new Build & Test workflow
* Add OS tests
* Wait for network idle for more reliable ready state
* Configure image snapshot testing and add example
* Remove example fixture file
* Adjust image snapshot threshold for local & CI tests
* Upload diff-output artifact
* Add failure() check to upload-artifact
* Bump image snapshot threshold for local & CI tests
* Set diffDirection
* Fix XHR caching in playwright tests
* Update image snapshot example and theshold
* Bump image snapshot threshold for local & CI tests
* Remove old workflows
* Bump image snapshot threshold for local & CI tests
* Bump image snapshot failureThreshold for local & CI tests
* Set failureThresholdType to percent
* Change image snapshot comparisonMethod to ssim
* Remove pixelMatch options (incompatible with ssim)
* Bump image snapshot failureThreshold
* Bump image snapshot failureThreshold
* Disable fast-fail to allow all checks to complete
* Rename workflow
* Disable fast-fail to allow all checks to complete
* Store pixel and ssim comparison configs
* Add link to image snapshot test
* Fix CI errors on Windows due to image size mismatch
* Attempt to fix macos e2e exit code 134 issue
* Update test.yml
* Update test.yml
* Update test.yml
* Fix --ci flag
* Set Jets to use --runInBand for macOS e2e
* Remove unnecessary macOS check
* Set image snapshot to runInProcess (macOS CI fix)
* Update test.yml
* Temporary failureThreshold change for debugging
* Upload os+node-specific diff artifacts
* Remove node version from diff artifact
* Revert "Remove node version from diff artifact"
This reverts commit 9cfcc4342b.
* Revert "Revert "Remove node version from diff artifact""
This reverts commit ad6c1891e4.
* Restoring failureThreshold after debugging
* Remove runInProcess option
* Revert "Remove runInProcess option"
This reverts commit 667ed6c870.
* Add node-specific artifact uploads
* Set ssim mode to fast and restore runInProcess
* Set failureThreshold to 0.01
* Updating to playwright@next for webkit fix
* Restore optimal ssim configuration
* Testing pixel vs. ssim image comparison
* Move shared test setup to unit/int/e2e setups
* Refactor test server setup
* Replace live-server with browser-sync
* Update script for running local docs site
- Only init GA plugin on public site
- Only init Gitter plugin on public site
- Only init Matomo plugin on public site
NOTE: Large diff is a result of initial Prettier formatting. Actual change limited to last <script> block on page.
* Allow launching test server preview with --start
* Add integration tests and refactor unit + e2e
* Unify docsifyInit() and cleanup
- Create unified docsifyInit() for jest and playwright
- Move shared helpers to /tests/helpers
- Update tests
- Update globals
* Fixed webkit routes by specifying ContentType
* Update snapshot
* Update dependencies
* Update tests to use unified docsifyInit()
* Remove Cypress (old e2e test environment)
* Update tests to run (unit/integration/e2e)
- Add new integration tests (Jest)
- Remove old unit tests (mocha+jsdom)
- Remove old e2e tests (Cypress)
* Remove Cypress-related dependency
* Remove mocha+chai+jsdom (old unit/int test env)
* Rename testing directories and scripts
- Rename /tests/ directory to /test/
- Rename script/task names by removing “jest” identifier
- Remove “test:jest-examples” script
* - Configure test server for availability with all tests (previously e2e only)
- Create identical docsifyInit() tests using Jest (integration) and Playwright (e2e)
- Update docsifyInit() to convert relative URLs to absolute URLs to work in both JSDOM and Playwright
- Update docsifyInit() to append style- and js-related tags using createElement instead of insertAdjacentHTML
- Update paths in test files to use unified docsifyInit()
- Added option to docsifyInit() to enable/disable formatted HTML output to console
- Removed vue.css as default docsify theme from docsifyInit()
- Removed outdated files
* Reorganize test files
* Fix basePath option
* Replace do-mock-ajax with xhr-mock
- Allows mocking all XMLHttpRequests instead of just those initiated via /src/core/fetch/ajax.js
- Allows JSDOM tests to use /lib/docsify.js instead of /src/core/index.js (same as Playwright tests)
- Allows JSDOM tests to use /docs site as test content
* Added new waitFor helpers
* Clean up globals
- Import globals from various files instead of manually adding them to ensure they are availability in Jest and eslint configurations
- Add middleware to server configuration for serving virtual “_blank.html” file
- Add BLANK_URL
- Rename TEST_URL to TEST_HOST
- Removed ./test/fixtures/ directory (blank page now served via server.js middleware)
- Added page.goto(BLANK_URL) call to global Playwright beforeEach() setup
* Add try/catch for waitForFunction callback
* Move playwright config into jest.config.js
* Add runInBand option to tests for reliability
* Remove unnecessary XHR Mock teardown
* Add —runInBand to test script
* Merge develop
* Cleanup
- Relocate carbon plugin script with other scripts
- Update zh-cn docs URL to align with other translatins (GitHub, not jsdelivr)
- Add major version locks to URLs
* Removed fixed host value from docs
* Updated test after merge (docsify version change)
* Added startPath for manual instance
* Remove Node 10 from CI tests
* Remove Node 10 from CI lint tests
This option allows to dynamically choose the index path depending on the path prefixes in auto mode. Thus, different path namespace could avoid index intersection (e.g., when having multiple locales)
* Fix search plugin will replace matching text
* Fix bug that will replace a unexpected text
* Fix bug that will replace a unexpected text
* Optimized
Co-authored-by: 沈唁 <52o@qq52o.cn>
Update embeded files documentation
Add example with front matter
Add various comments I used to understand code
Updated front matter to have installed flag
Added function to parse front matter
Added intercept to remove front matter for embed
Koy Zhuang