diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..90d4069 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,1844 @@ +--- +title: CHANGELOG +layout: default +--- + +# CHANGELOG + +All notable user-facing changes to this project are documented in this file. + +{: .highlight } +The project underwent a major maintenance shift in March 2022. + +## HEAD + +{: .note } +This website is built from the `HEAD` of the `main` branch of the theme repository. + +Code changes to `main` that are *not* in the latest release: + +- N/A + +Docs changes made since the latest release: + +- N/A + +## Release v0.10.0 + +Hi folks! This minor release adds one of our most-requested features: unlimited multi-level navigation (also known as recursive navigation). Huge thanks to [@pdmosses] for his wonderful work in implementing this feature! + +This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support! + +### Using Release `v0.10.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.9.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.10.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.10.0" +``` + +To use and pin a previous version of the theme, replace the `0.10.0` with the desired release tag. + +### New Features + +- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1431] + +### Documentation + +- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440] +- Added: sitemap (via `jekyll-sitemap` plugin) by [@mattxwang] in [#1530] +- Fixed: (non-systemic) accessibility issues flagged by aXe by [@mattxwang] in [#1531] + +[#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431 +[#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440 +[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1530 +[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1531 + +## Release v0.9.0 + +Hi folks! This minor release adds a `nav_enabled` set of variables to enable/disable the navigation at a site, layout, and page level --- and uses that to add search and auxilary links to the `minimal` layout. In addition, it fixes `search-data.json` corruption with default layouts and some minor CSS/SCSS issues. + +This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support! + +### Using Release `v0.9.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.9.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.9.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.9.0" +``` + +To use and pin a previous version of the theme, replace the `0.9.0` with the desired release tag. + +### New Features + +- Added: `nav_enabled` site, layout, and page-level variable to selectively show or hide the side/mobile menu by [@kevinlin1] in [#1441] +- Added: site-wide search bar and auxiliary links to the `minimal` layout by [@kevinlin1] in [#1441] + +### Bugfixes + +- Fixed: protect `search-data.json` file from front matter default for layout by [@mattxwang] in [#1468] +- Fixed: Sass mixed declarations by [@bobvandevijver] in [#1495] +- Fixed: redundant `monospace` in `pre`, `code`, `kbd`, `samp` reset by [@mattxwang] in [#1508] + +### Documentation + +- Docs: Explained the `nav_enabled` variables as an alternative to using the minimal layout [@kevinlin1] in [#1441]. + +### New Contributors + +- [@bobvandevijver] made their first contribution in [#1495] + +[@bobvandevijver]: https://github.com/bobvandevijver + +[#1441]: https://github.com/just-the-docs/just-the-docs/pull/1441 +[#1468]: https://github.com/just-the-docs/just-the-docs/pull/1468 +[#1495]: https://github.com/just-the-docs/just-the-docs/pull/1495 +[#1508]: https://github.com/just-the-docs/just-the-docs/pull/1508 + +## Release v0.8.2 + +Hi everyone! This patch release fixes a bug where a default layout with unrestricted `scope` (`path: ""`) breaks JavaScript functionality. Users who do not use a default layout with unrestricted `scope` should not be affected. This should be a straightforward upgrade for all users. Thank you to [@pdmosses] for triaging and fixing the bug! + +### Bugfixes + +- Fixed: Protect theme JS file from front matter default for layout by [@pdmosses] in [#1447] + +[#1447]: https://github.com/just-the-docs/just-the-docs/pull/1447 + +## Release v0.8.1 + +Hi folks! This patch release fixes a bug introduced in `0.8.0` that affects users who build their sites in strict mode. It is a straightforward upgrade that should require no manual migration changes. Thank you to [@Zarthus] for quickly catching and fixing this bug! + +### Bugfixes + +- Fixed: Liquid filter typo in breadcrumb component (`strip` instead of `trim`) by [@Zarthus] in [#1434] + +### Documentation + +- Build docs site using strict mode and `strict_filters` by [@Zarthus] in [#1435] + +### New Contributors + +- [@Zarthus] made their first contribution in [#1434] + +[@Zarthus]: https://github.com/Zarthus + +[#1434]: https://github.com/just-the-docs/just-the-docs/pull/1434 +[#1435]: https://github.com/just-the-docs/just-the-docs/pull/1435 + +## Release v0.8.0 + +Hi folks! This first minor release of 2024 has a short number of changes: a large improvement of build times for large sites, a new keyboard shortcut to focus the search bar, and sidebar navigation bugfixes for "pretty" URLs (with `.html` omitted) and the clickable area on Safari. This release has no explicit breaking changes and should be a straightforward upgrade for most (if not all) users. + +### Using Release `v0.8.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.8.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.8.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.8.0" +``` + +To use and pin a previous version of the theme, replace the `0.8.0` with the desired release tag. + +### New Features + +- Added: configurable keyboard shortcut to focus search input by [@kcromanpl-bajra] in [#1411] + +### Bugfixes + +- Fixed: quicker build by [@pdmosses] in [#1397] +- Fixed: incorrect navigation when `.html` omitted from URL by [@pdmosses] in [#1374] +- Fixed: incorrect positioning of clickable area for navigation links on Safari by [@mattxwang] in [#1403] + +### Documentation + +- Add documentation to "Navigation Structure" on grouping pages with collections by [@mitchnemirov] in [#1390] + +### New Contributors + +- [@mitchnemirov] made their first contribution in [#1390] +- [@kcromanpl-bajra] made their first contribution in [#1411] + +[@mitchnemirov]: https://github.com/mitchnemirov +[@kcromanpl-bajra]: https://github.com/kcromanpl-bajra + +[#1374]: https://github.com/just-the-docs/just-the-docs/pull/1374 +[#1390]: https://github.com/just-the-docs/just-the-docs/pull/1390 +[#1397]: https://github.com/just-the-docs/just-the-docs/pull/1397 +[#1403]: https://github.com/just-the-docs/just-the-docs/pull/1403 +[#1411]: https://github.com/just-the-docs/just-the-docs/pull/1411 + +## Release v0.7.0 + +Hi folks! This is a minor release that adds a new configuration option for opening external links in a new tab and provides many bugfixes (in both correctness and performance) for Just the Docs users with large sites. We anticipate that for most users, this is a straightforward upgrade. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme. + +### Migrating to `v0.7.0` + +**Migration**: users will need to migrate if: + +- they overrode `_includes/nav.html`, which has moved to `_includes/components/nav.html` +- they have an element with the IDs `jtd-nav-activation` or `jtd-head-nav-stylesheet` + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.7.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.7.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.7.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.7.0" +``` + +To use and pin a previous version of the theme, replace the `0.7.0` with the desired release tag. + +### New Features + +- Added: configuration options for opening external links in new tab by [@CarbonNeuron] in [#1360] + +### Bugfixes + +- Fixed: remove href from the navigation link to the current page by [@pdmosses] in [#1356] +- Fixed: improve build time by [@pdmosses] in [#1358] +- Fixed: erroneous parentheses in `site_nav` conditional by [@mattxwang] in [#1366] +- Fixed: navigation scroll to active link regression by [@pdmosses] in [#1367] +- Fixed: invalid CSS rules in head elements by [@pdmosses] in [#1368] +- Fixed: accidental disabling of forward-declared stylesheets by [@mattxwang] in [#1373] + +{: .warning } +[#1358] moved `_includes/nav.html` to the `_includes/components` directory, +Users who were overriding that file will need to adjust their sites accordingly. + +### Documentation: + +- Docs: fix typos in `CHANGELOG` and `MIGRATION` by [@thapasusheel] in [#1377] + +### New Contributors + +- [@CarbonNeuron] made their first contribution in [#1360] +- [@thapasusheel] made their first contribution in [#1377] + +[@CarbonNeuron]: https://github.com/CarbonNeuron +[@thapasusheel]: https://github.com/thapasusheel + +[#1356]: https://github.com/just-the-docs/just-the-docs/pull/1356 +[#1358]: https://github.com/just-the-docs/just-the-docs/pull/1358 +[#1360]: https://github.com/just-the-docs/just-the-docs/pull/1360 +[#1366]: https://github.com/just-the-docs/just-the-docs/pull/1366 +[#1367]: https://github.com/just-the-docs/just-the-docs/pull/1367 +[#1368]: https://github.com/just-the-docs/just-the-docs/pull/1368 +[#1373]: https://github.com/just-the-docs/just-the-docs/pull/1373 +[#1377]: https://github.com/just-the-docs/just-the-docs/pull/1377 + +## Release v0.6.2 + +Hi all, this is a small patch release that includes two changes: adding a missing Windows emoji font fallback, and removing some (now-unused) code introduced in 0.6. + +### Bugfixes + +- Fixed: Windows emoji font fallback by [@flanakin] in [#1337] +- Removed: unused `.passive` toggle in navigation by [@pdmosses] in [#1335] + +[#1335]: https://github.com/just-the-docs/just-the-docs/pull/1335 +[#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337 + +### New Contributors + +- [@flanakin] made their first contribution in [#1337] + +[@flanakin]: https://github.com/flanakin + +## Release v0.6.1 + +Hi all, this is a small patch release that only includes one change: resolving a bug introduced in 0.6.0 that causes a JS error for pages excluded from navigation. + +### Bugfixes + +- Fixed: JS error for pages excluded from navigation by [@pdmosses] in [#1332] + +[#1332]: https://github.com/just-the-docs/just-the-docs/pull/1332 + +## Release v0.6.0 + +Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme. + +### Migrating to `v0.6.0` + +**Migration**: users will need to migrate if: + +- they have an existing `_includes` file named `favicon.html`, `head_nav.html`, or `css/activation.scss.liquid` +- they have code that refers to `#main-content-wrap` +- they override the default `light` theme's code, or the theme-loading logic +- they have different favicons for different pages + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.6.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.6.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.6.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.6.0" +``` + +To use and pin a previous version of the theme, replace the `0.6.0` with the desired release tag. + +### New Features and Bugfixes + +- Added: `$color-scheme` theme variable to specify `color-scheme` for `:root` by [@sigv] in [#1280] +- Fixed: build times for large sites by [@pdmosses] in [#1244] +- Fixed: missing closing `` tag in `sidebar.html` by [@mattxwang] in [#1304] +- Fixed: removed duplicate `#main-content-wrap` minimal and default layouts by [@mattxwang] in [#1305] + +### Documentation + +{: .warning } +The theme docs are unversioned, and already reflect the above changes. + +Docs changes: + +- A [footnote]({% link index.md %}#fn:js-disabled) in the configuration docs explains how disabling JavaScript affects the display of navigation links when browsing folded collections. +- Invalid HTML has been removed from most documentation examples. + +### New Contributors + +- [@sigv] made their first contribution in [#1280] + +[@sigv]: https://github.com/sigv +[#1244]: https://github.com/just-the-docs/just-the-docs/pull/1244 +[#1280]: https://github.com/just-the-docs/just-the-docs/pull/1280 +[#1304]: https://github.com/just-the-docs/just-the-docs/pull/1304 +[#1305]: https://github.com/just-the-docs/just-the-docs/pull/1305 + +## Release v0.5.4 + +Hi all, this is a small patch release that only includes one change: fixing a style clash between Mermaid's labels and Just the Docs' labels. + +*Note: for subsequent patch releases, we will omit migration instructions (for brevity). In all cases, immediate migration should be backwards-compatible. Refer to previous major or minor update instructions for more information.* + +### Bugfixes + +- Fixed: Mermaid labels inheriting theme `.label` styling by [@mattxwang] in [#1278] + +[#1278]: https://github.com/just-the-docs/just-the-docs/pull/1278 + +## Release v0.5.3 + +Hi all, this is a minor patch release that only includes one change: changing all text-based CSS properties to use `rem` instead of hard-coded `px` values. This has two effects: + +1. All deprecation warnings are now fixed on build; you should now get a clean build with `jekyll build`. +2. We have **deprecated the `$root-font-size` SCSS variable**. We will remove it in an upcoming release of the theme. + +If you use the stock Just the Docs theme, this release should have no impact on your final built site. If you change the `$root-font-size` SCSS variable, you might experience light layout shifts. + +### Using Release `v0.5.3` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.3` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.3 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.3" +``` + +To use and pin a previous version of the theme, replace the `0.5.3` with the desired release tag. + +### Bugfixes + +- Fixed: font-size scaling for text-related CSS properties by using `rem` instead of fixed `px` values; deprecate `$root-font-size` by [@mattxwang] in [#1169] + +[#1169]: https://github.com/just-the-docs/just-the-docs/pull/1169 + +## Release v0.5.2 + +Hi all, this is a minor patch release that mostly focuses on accessibility. Since we follow semantic versioning, this should be a smooth upgrade with no breaking changes. + +In addition, the theme docs website has a new canonical URL: . We've also retroactively published the theme docs website for version `v0.3.3` at . Thank you to our GitHub sponsors for funding our domain name! + +### Using Release `v0.5.2` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.2` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.2 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.2" +``` + +To use and pin a previous version of the theme, replace the `0.5.2` with the desired release tag. + +### Bugfixes + +- Fixed: liquid variable leakage in navigation components by [@pdmosses] in [#1243] +- Fixed: ARIA roles and labels for search, header, logo, mobile menu button, and main content by [@joelhawksley] in [#1259] +- Fixed: ARIA labels for all anchors with `href="#"`; adds `aria-pressed` information for toggles by [@mattxwang] in [#1262] + +### New Contributors + +- [@joelhawksley] made their first contribution in [#1259] + +[@joelhawksley]: https://github.com/joelhawksley + +[#1243]: https://github.com/just-the-docs/just-the-docs/pull/1243 +[#1259]: https://github.com/just-the-docs/just-the-docs/pull/1259 +[#1262]: https://github.com/just-the-docs/just-the-docs/pull/1262 + +## Release v0.5.1 + +Hi all, this is a very small minor patch release that has two small behavioral bugfixes: fixing a regression introduced in `v0.5.0` on Safari versions `<16.4` (broken media query), and the copy code button providing incorrect feedback in insecure browser contexts. This should be a smooth upgrade with no breaking changes. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.5.1` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.1` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.1 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.1" +``` + +To use and pin a previous version of the theme, replace the `0.5.1` with the desired release tag. + +### Bugfixes + + +- Fixed: disable copy code button in insecure contexts [@rmoff] in [#1226] +- Fixed: context-based media feature not supported by Safari `<16.4` by [@mattxwang] in [#1240] + +### Documentation + +- Added: document copy code button requiring secure context by [@rmoff] in [#1225] +- Fixed: typo ("them" → "theme") in MIGRATION.md by [@waldyrious] in [#1219] +- Fixed: `font-weight` typo (Utilities > Typography) by [@mattxwang] in [#1229] +- Fixed: `just the docs` typo in migration guide by [@mattxwang] in [#1230] + +### New Contributors +- [@rmoff] made their first contribution in [#1225] + +[#1219]: https://github.com/just-the-docs/just-the-docs/pull/1219 +[#1225]: https://github.com/just-the-docs/just-the-docs/pull/1225 +[#1226]: https://github.com/just-the-docs/just-the-docs/pull/1226 +[#1229]: https://github.com/just-the-docs/just-the-docs/pull/1229 +[#1230]: https://github.com/just-the-docs/just-the-docs/pull/1230 +[#1240]: https://github.com/just-the-docs/just-the-docs/pull/1240 + +[@rmoff]: https://github.com/rmoff + +## Release v0.5.0 + +Hope your April is going well! This new release of Just the Docs is relatively minor. It has one **breaking change**: we've reverted the import order of `setup.scss` to be *before* color schemes. In addition, we include two requested fixes: color contrast issues with `::selection` and using Just the Docs with mermaid versions `>=10`. + +We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to `v0.4.2` or who do not have a custom `setup.scss` are guaranteed no breaking changes. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Migrating to `v0.5.0` + +**Migration**: users with a custom `setup.scss` cannot rely on variables or functions defined in `color_scheme`. This reverts to the behaviour in `v0.4.1`. Users should instead move those variables or functions to the `color_scheme` files themselves. + +For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/). + +### Using Release `v0.5.0` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.5.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.5.0 +``` + +To use this version explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.5.0" +``` + +To use and pin a previous version of the theme, replace the `0.5.0` with the desired release tag. + +### Bugfixes + +- **Reverted (breaking)**: "Fix import order for `setup.scss` (#1184)" by [@mattxwang] in [#1209] +- Fixed: color contrast issues with `::selection` (reverting to browser defaults) [@mattxwang] in [#1208] +- Fixed: mermaid `v10`, bundle all mermaid code in component by [@mattxwang] in [#1190] +- Removed: unused images (`just-the-docs.png`, `search.svg`) by [@mattxwang] in [#1107] +- Removed: `CODE_OF_CONDUCT`, `docker-compose`, and `Dockerfile` files from site by [@mattxwang] in [#1187] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0](https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0) + +[#1107]: https://github.com/just-the-docs/just-the-docs/pull/1107 +[#1187]: https://github.com/just-the-docs/just-the-docs/pull/1187 +[#1190]: https://github.com/just-the-docs/just-the-docs/pull/1190 +[#1208]: https://github.com/just-the-docs/just-the-docs/pull/1208 +[#1209]: https://github.com/just-the-docs/just-the-docs/pull/1209 + +## Release v0.4.2 + +Hello! We're back again with another small release. Like `v0.4.1`, this release is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can [opt-in to our old highlighting theme](https://just-the-docs.com/docs/customization/#deprecated-legacy_light) by using `legacy_light` instead of `light`. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.2` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.2` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.2" +``` + +To use and pin a previous version of the theme, replace the `0.4.2` with the desired release tag. + +### Bugfixes + +- Fixed: light scheme code highlighting contrast issues; updated to use Atom's One Light colors, consolidate theme variables by [@mattxwang] in [#1166] +- Fixed: duplicate import of `color_schemes` by [@mattxwang] in [#1173] +- Fixed: import order for `setup.scss` by [@mattxwang] in [#1184] +- Removed: unused dark syntax themes by [@mattxwang] in [#1192] + +### Documentation + +- Added: docs for using mermaid with AsciiDoc by [@flyx] in [#1182] + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2](https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2) + +[#1166]: https://github.com/just-the-docs/just-the-docs/pull/1166 +[#1173]: https://github.com/just-the-docs/just-the-docs/pull/1173 +[#1182]: https://github.com/just-the-docs/just-the-docs/pull/1182 +[#1184]: https://github.com/just-the-docs/just-the-docs/pull/1184 +[#1192]: https://github.com/just-the-docs/just-the-docs/pull/1192 + +## Release v0.4.1 + +Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible. + +As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs! + +### Using Release `v0.4.1` + +Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.1" +``` + +To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag. + +### Bugfixes + +- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165] +- Fixed: AsciiDoc code block styling by [@flyx] in [#1168] +- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177] +- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167] + +### Documentation + +- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108] + +### New Contributors + +- [@flyx] made their first contribution in [#1168] +- [@Dima-369] made their first contribution in [#1177] + +[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108 +[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165 +[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167 +[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168 +[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177 + +[@flyx]: https://github.com/flyx +[@Dima-369]: https://github.com/Dima-369 + +**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1) + +## Release v0.4.0 + +We're so excited to release Just the Docs `v0.4.0`. This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme. + +### Brief Overview - Highlighted Changes + +`v0.4.0` contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes: + +- better support for dark theme: dark highlighting, search input color +- [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content +- [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library +- [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets +- external navigation links +- major improvements to nav generation efficiency and robustness +- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content) +- [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature) +- [new custom includes](https://just-the-docs.com/docs/customization/#override-includes): table of contents heading, navigation panel footer, search placeholder, lunr search indices +- bugfixes involving WEBrick and Ruby 3, Liquid processing in CSS comments, nested task lists, relative URLs, scroll navigation, corrupted search data from rake, breadcrumbs, and more! +- more documentation for [custom includes](https://just-the-docs.com/docs/customization/#override-includes), this changelog, and the [migration guide](https://just-the-docs.com/MIGRATION/) + +*After usage instructions and the roadmap, we enumerate all changes from `v0.3.3`.* + +### Using Release `v0.4.0` + +Unlike pre-releases, `v0.4.0` is a new semver minor release for the theme. That means that users who have not pinned the theme version will be **automatically upgraded to `v0.4.0` the next time they build their site**. + +To use this release explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0" +``` + +If you would prefer to not upgrade, you can enforce that explicitly: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Migration Guide and Strategies + +We've developed a new [migration guide](https://just-the-docs.com/MIGRATION/) for users to migrate from version `v0.3.3` to `v0.4.0`. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site. + +**For the vast majority of users, we do not anticipate that this will be a breaking change.** The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes. + +Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from `v0.4.0.rc1` to `v0.4.0.rc5`; this breaks down the release into small chunks, each of which should be easier to upgrade. `v0.4.0.rc5` is identical to this release. + +For support with migrating to `v0.4.0`, [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Roadmap (What's Next?) + +Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future! + +Broadly, many features are still on the radar. We anticipate the rest of `v0.4.x` to be bugfixes surrounding this new release. + +For version `v0.5`, our roadmap includes: + +- a theme toggle (light/dark mode), with automatic theme switching based on browser preferences +- better GDPR compliance for analytics +- multi-level/recursive navigation (unlimited hierarchy of child pages) + +In future versions, we also plan on: + +- adding better dark theme defaults +- adding better internationalization support +- exploring offline PDF generation +- improving accessibility within the theme +- improving search functionality +- refactoring and improving the robustness of our codebase + +Have ideas for what's next, or want to get involved? [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! We're looking for more contributors and maintainers to help us develop the theme. + +### New Features + +- Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +- Added: custom favicon `_includes` by [@burner1024] in [#364] +- Added: set color for search input by [@pdmosses] in [#498] +- Added: search placeholder configuration by [@mattxwang] in [#613] +- Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +- Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +- Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +- Added: mermaid.js support by [@nascosto] in [#857] +- Added: support for external navigation links by [@SPGoding] in [#876] +- Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes + +- Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +- Fixed: nested task lists (#517) by [@pdmosses] in [#855] +- Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +- Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +- Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +- Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +- Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +- Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +- Fixed: allow links to wrap by [@pdmosses] in [#905] +- Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Maintenance + +- Added: VScode devcontainer by [@max06] in [#783] +- Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +- Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +- Updated: new repo path by [@pmarsceill] in [#775] +- Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +- Updated: README by [@pmarsceill] in [#777] +- Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +- Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +- Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] +- Deleted: unused script directory by [@mattxwang] in [#937] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Documentation + +- Added: docs on how to break an `ol` by [@pdmosses] in [#856] +- Added: docs for custom includes by [@nathanjessen] in [#806] +- Added: document caveat about variable dependencies by [@waldyrious] in [#555] +- Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Added: warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Added: migration guide by [@pdmosses] in [#1059] +- Added: label new features introduced in `v0.4` by [@mattxwang] in [#1138] +- Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +- Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +- Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +- Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +- Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +- Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +- Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +- Fixed: spacing in toc example by [@henryiii] in [#835] +- Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +- Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Fixed: typo in changelog links [@koppor] in [#1000] +- Fixed: two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Fixed: "View Typography Utilities" link by [@agabrys] in [#1130] +- Fixed: broken relative page links by [@mattxwang] in [#1106] +- Fixed: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Updated: homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Updated: README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Updated: `README` demo video by [@codewithfan] in [#1097] + +### New Contributors + +- [@AdityaTiwari2102] made their first contribution in [#477] +- [@svrooij] made their first contribution in [#544] +- [@alexsegura] made their first contribution in [#519] +- [@burner1024] made their first contribution in [#364] +- [@JeffGuKang] made their first contribution in [#221] +- [@dougaitken] made their first contribution in [#782] +- [@max06] made their first contribution in [#783] +- [@sehilyi] made their first contribution in [#499] +- [@nathanjessen] made their first contribution in [#473] +- [@waldyrious] made their first contribution in [#549] +- [@MichelleBlanchette] made their first contribution in [#554] +- [@henryiii] made their first contribution in [#835] +- [@jmertic] made their first contribution in [#726] +- [@jacobhq] made their first contribution in [#846] +- [@UnclassedPenguin] made their first contribution in [#814] +- [@alyssais] made their first contribution in [#829] +- [@nascosto] made their first contribution in [#857] +- [@SPGoding] made their first contribution in [#876] +- [@iridazzle] made their first contribution in [#727] +- [@ivanskodje] made their first contribution in [#891] +- [@Eisverygoodletter] made their first contribution in [#893] +- [@robinpokorny] made their first contribution in [#940] +- [@olgarithms] made their first contribution in [#951] +- [@manuelhenke] made their first contribution in [#941] +- [@JPrevost] made their first contribution in [#950] +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +## Pre-release v0.4.0.rc5 + +Hi everyone, we're so excited to finally release `v0.4.0`! For posterity's sake, we're going to release `v0.4.0.rc5` and then immediately re-release it as `v0.4.0`; this should make it more clear what changes were introduced in the lead up to the minor release. + +This RC does not introduce any major user-facing features. It adds more customizability for custom SCSS variables (fixing a bug with callout introduction order), `lunr` indexing, and loading `mermaid` locally. In addition, it fixes bugs introduced in `.rc4`: incorrect CSS, inconsistencies with code block backgrounds in dark theme, and the copy code button. It also adds a migration guide for users coming from `v0.3.3`. + +### Trying out pre-release `v0.4.0.rc5` + +Similar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc5 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc5" +``` + +By default, **users will not be upgraded to `0.4.0.rc5`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: includes for custom `lunr` Liquid and JS code by [@diablodale] in [#1068] +- Added: new `_sass/custom/setup.scss` for variable definition by [@mattxwang] in [#1135] +- Added: configuration key to load a local version of mermaid by [@fabrik42] in [#1153] + +### Bugfixes and Maintenance + +- Fixed: incorrect `padding` property value pair in `search.scss` by [@kevinlin1] in [#1123] +- Fixed: minor spacing and comment nits by [@EricFromCanada] in [#1128] +- Fixed: exclude images from being bundled with gem by [@m-r-mccormick] in [#1142] +- Fixed: dark theme code block background, line number colors by [@m-r-mccormick] in [#1124] +- Fixed: copy code button interaction with kramdown line numbers by [@mattxwang] in [#1143] + +### Docs + +- Docs: add a migration guide by [@pdmosses] in [#1059] +- Docs: update `README` demo video by [@codewithfan] in [#1097] +- Docs: update "View Typography Utilities" link by [@agabrys] in [#1130] +- Docs: fix broken relative page links by [@mattxwang] in [#1106] +- Docs: clarify steps to add custom `lunr` index code by [@diablodale] in [#1139] +- Docs: label new features introduced in `v0.4` by [@mattxwang] in [#1138] + +### New Contributors + +- [@kevinlin1] made their first contribution in [#1123] +- [@codewithfan] made their first contribution in [#1097] +- [@agabrys] made their first contribution in [#1130] +- [@diablodale] made their first contribution in [#1068] +- [@m-r-mccormick] made their first contribution in [#1142] +- [@fabrik42] made their first contribution in [#1153] + +[#1059]: https://github.com/just-the-docs/just-the-docs/pull/1059 +[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068 +[#1097]: https://github.com/just-the-docs/just-the-docs/pull/1097 +[#1106]: https://github.com/just-the-docs/just-the-docs/pull/1106 +[#1123]: https://github.com/just-the-docs/just-the-docs/pull/1123 +[#1124]: https://github.com/just-the-docs/just-the-docs/pull/1124 +[#1128]: https://github.com/just-the-docs/just-the-docs/pull/1128 +[#1130]: https://github.com/just-the-docs/just-the-docs/pull/1130 +[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135 +[#1138]: https://github.com/just-the-docs/just-the-docs/pull/1138 +[#1139]: https://github.com/just-the-docs/just-the-docs/pull/1139 +[#1142]: https://github.com/just-the-docs/just-the-docs/pull/1142 +[#1143]: https://github.com/just-the-docs/just-the-docs/pull/1143 +[#1153]: https://github.com/just-the-docs/just-the-docs/pull/1153 + +[@agabrys]: https://github.com/agabrys +[@codewithfan]: https://github.com/codewithfan +[@diablodale]: https://github.com/diablodale +[@fabrik42]: https://github.com/fabrik42 +[@kevinlin1]: https://github.com/kevinlin1 +[@EricFromCanada]: https://github.com/EricFromCanada +[@m-r-mccormick]: https://github.com/m-r-mccormick + +## Pre-release v0.4.0.rc4 + +Happy new year! We're celebrating with another pre-release, with features that should help theme users better adapt to changes moving forward. **We aim to re-release this as `v0.4.0`, with only few changes**. + +Notable new additions include: + +- modular site components, which split up the site into smaller reusable components; advanced theme users can then remix layouts quickly without duplication +- a "copy code" button to code blocks +- fixing bugs in generated TOCs and navigation from previous prereleases +- various cleanups of CSS and HTML markup + +The roadmap to `v0.4.0` is small. We are only looking to: + +- finish a migration guide, so users can easily upgrade from `v0.3.3` to `v0.4.0` +- fix one last bug relating to callouts and custom colors +- fix any new bugs introduced by this pre-release + +Have any questions, thoughts, or concerns? We'd love to hear from you! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc4` + +Similar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc4 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc4" +``` + +By default, **users will not be upgraded to `0.4.0.rc4`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### New Features + +- Added: support multiple Google Analytics tracking IDs, document UA -> GA4 switch by [@MichelleBlanchette] in [#1029] +- Added: copy code button to code snippets by [@simonebortolin] in [#945] +- Added: restore simple configuration of `favicon.ico` via `site.static_files` by [@pdmosses] in [#1095] +- Added: modularize site components by [@mattxwang] in [#1058] + +### Bugfixes and Maintenance + +- Fixed: incorrect disambiguation in generated TOCs by [@pdmosses] in [#999] +- Fixed: duplicated external links in collections by [@pdmosses] in [#1001] +- Fixed: import order of `custom.scss`; puts at end by [@deseo] in [#1010] +- Fixed: top-level active link styling by [@pdmosses] in [#1015] +- Fixed: external links for sites with no pages by [@pdmosses] in [#1021] +- Fixed: duplicate `title` if `jekyll-seo-tag` not in users's plugins by [@Tom-Brouwer] in [#1040] +- Fixed: removes (duplicate) `favicon.html`, shifts content to `head_custom.html` by [@mattxwang] in [#1027] +- Fixed: add `reversed`, deprecate `desc` for nav `child_nav_order` by [@jmertic] in [#1061] +- Fixed: `child.child_nav_order` to `node.child_nav_order` by [@mattxwang] in [#1065] +- Fixed: remove all uses of `/` as SASS division by [@mattxwang] in [#1074] + - note: this was originally merged as [#1074] with a bug; it was reverted in [#1076], and then reimplemented in [#1077] +- Fixed: skip nav collection generation when site has no pages by [@pdmosses] in [#1092] +- Fixed: standardize SCSS with `declaration-block-no-redundant-longhand-properties` by [@simonebortolin] in [#1102] +- Fixed: incorrect `padding` property value pair in `labels.scss` by [@SConaway] in [#1104] +- Fixed: various bugs with copy code button by [@simonebortolin] in [#1096] +- Fixed: replace inline styling for `` icons by [@captn3m0] in [#1110] +- Vendor: update `jekyll-anchor-headings`, `lunr.js` by [@mattxwang] in [#1071] + +### Docs + +- Docs: fix typo in changelog links [@koppor] in [#1000] +- Docs: update homepage (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1018] +- Docs: update README (focus: new features, conciseness, deduplication) by [@pdmosses] in [#1019] +- Docs: fix two bugs in "Customization" (custom favicon, new annotation) by [@mattxwang] in [#1090] +- Docs: Add warning about mandatory `_`-prefix for collections by [@max06] in [#1091] +- Docs: remove Google Analytics on main site by [@mattxwang] in [#1113] + +### New Contributors + +- [@koppor] made their first contribution in [#1000] +- [@deseo] made their first contribution in [#1010] +- [@Tom-Brouwer] made their first contribution in [#1040] +- [@simonebortolin] made their first contribution in [#945] +- [@SConaway] made their first contribution in [#1104] +- [@captn3m0] made their first contribution in [#1110] + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc3...v0.4.0.rc4 + +[#945]: https://github.com/just-the-docs/just-the-docs/pull/945 +[#999]: https://github.com/just-the-docs/just-the-docs/pull/999 +[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000 +[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001 +[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010 +[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015 +[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018 +[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019 +[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021 +[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027 +[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029 +[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040 +[#1058]: https://github.com/just-the-docs/just-the-docs/pull/1058 +[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061 +[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065 +[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071 +[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074 +[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076 +[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077 +[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090 +[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091 +[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092 +[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095 +[#1096]: https://github.com/just-the-docs/just-the-docs/pull/1096 +[#1102]: https://github.com/just-the-docs/just-the-docs/pull/1102 +[#1104]: https://github.com/just-the-docs/just-the-docs/pull/1104 +[#1110]: https://github.com/just-the-docs/just-the-docs/pull/1110 +[#1113]: https://github.com/just-the-docs/just-the-docs/pull/1113 + +[@captn3m0]: https://github.com/captn3m0 +[@deseo]: https://github.com/deseo +[@koppor]: https://github.com/koppor +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@simonebortolin]: https://github.com/simonebortolin +[@SConaway]: https://github.com/SConaway +[@Tom-Brouwer]: https://github.com/Tom-Brouwer + +## Pre-release v0.4.0.rc3 + +Hi there! This is (actually) hopefully the last prerelease before `v0.4.0`; in particular, if we find that this prerelease is stable, we'll re-release it as `v0.4.0`. + +In general, this is a more mature pre-release; there are few new features. However, we'll highlight [@pdmosses]'s work in [#992] to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, **it is technically a breaking change**, and we suggest testing your site before upgrading to this prerelease. + +We want your feedback! Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +As soon as we get stable test results from major downstream users, we'll push out a `v0.4.0` ASAP - closing out almost 2 years of backlogged work! + +### Trying out pre-release `v0.4.0.rc3` + +Similar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc3" +``` + +By default, **users will not be upgraded to `0.4.0.rc3`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +Broadly, this prerelease is feature-light! + +- Added: styling for `
` by [@mattxwang] in [#965] +- Added: custom include for TOC heading by [@pdmosses] in [#980] + +### Bugfixes and Experimental Features + +*Note*: experimental nav optimization may be unstable. Please give us feedback! + +- Added: experimental nav optimization for simple cases by [@pdmosses] in [#992] +- Fixed: spacing issue when search is disabled by [@henryiii] in [#960] +- Fixed: active grandchild link class by [@pdmosses] in [#962] +- Fixed: HTML validation issues (W3C validator) by [@mattxwang] in [#964] +- Fixed: link styling now uses `text-decoration` values by [@mattxwang] in [#967] +- Fixed: cleaning up Jekyll excludes by [@pdmosses] in [#985] +- Fixed: docs, narrow styling for code highlighting with line numbers by [@pdmosses] in [#974] +- Fixed: default syntax highlighting in custom color schemes [@pdmosses] in [#986] + +[#965]: https://github.com/just-the-docs/just-the-docs/pull/965 +[#960]: https://github.com/just-the-docs/just-the-docs/pull/960 +[#962]: https://github.com/just-the-docs/just-the-docs/pull/962 +[#964]: https://github.com/just-the-docs/just-the-docs/pull/964 +[#967]: https://github.com/just-the-docs/just-the-docs/pull/967 +[#974]: https://github.com/just-the-docs/just-the-docs/pull/974 +[#980]: https://github.com/just-the-docs/just-the-docs/pull/980 +[#985]: https://github.com/just-the-docs/just-the-docs/pull/985 +[#986]: https://github.com/just-the-docs/just-the-docs/pull/986 +[#992]: https://github.com/just-the-docs/just-the-docs/pull/992 + +[@henryiii]: https://github.com/henryiii + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3 + +## Pre-release v0.4.0.rc2 + +{: .warning } +This website includes docs for some new features that are not available in `v0.4.0.rc1` and `v0.3.3`! + +Hey there! This is likely the last pre-release before releasing `v0.4.0`, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight: + +- significant improvement on build time of navigation panel by [@pdmosses] + - this is big: for a community member with over 300 pages, we shortened the build time from 3 minutes to 30 seconds! +- improved accessibility features led by [@JPrevost] +- more docs! + +The intention of this release candidate is to gather even more feedback on a potential `v0.4.0`. As it stands, we have not encountered any breaking changes with early adopters of `v0.4.0.rc1`. If you encounter any - for either of our pre-releases - please let us know! + +### Trying out pre-release `v0.4.0.rc2` + +Similar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc2 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc2" +``` + +By default, **users will not be upgraded to `0.4.0.rc2`**. To enforce that explicitly, either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +### Features + +- Added: accessible titles to nested page nav toggle by [@JPrevost] in [#950] +- Added: better title styling for AsciiDoc examples by [@alyssais] in [#944] +- Added: docs for custom search placeholder by [@mattxwang] in [#939] +- Added: provide ability to skip to main content by [@JPrevost] in [#949] +- Fixed: exclude `vendor/` in Jekyll config by [@manuelhenke] in [#941] +- Fixed: improve build time of navigation panel by [@pdmosses] in [#956] + +[#950]: https://github.com/just-the-docs/just-the-docs/pull/950 +[#944]: https://github.com/just-the-docs/just-the-docs/pull/944 +[#939]: https://github.com/just-the-docs/just-the-docs/pull/939 +[#949]: https://github.com/just-the-docs/just-the-docs/pull/949 +[#941]: https://github.com/just-the-docs/just-the-docs/pull/941 +[#956]: https://github.com/just-the-docs/just-the-docs/pull/956 + +[@alyssais]: https://github.com/alyssais + +### Documentation and Maintenance + +- Added: docs load mermaid.js by default by [@mattxwang] in [#935] +- Fixed: table of contents on search docs by [@robinpokorny] in [#940] +- Fixed: broken docs link (custom footer) by [@olgarithms] in [#951] +- Fixed: clarify version docs by [@pdmosses] in [#955] +- Deleted: unused script directory by [@mattxwang] in [#937] + +[#935]: https://github.com/just-the-docs/just-the-docs/pull/935 +[#940]: https://github.com/just-the-docs/just-the-docs/pull/940 +[#951]: https://github.com/just-the-docs/just-the-docs/pull/951 +[#955]: https://github.com/just-the-docs/just-the-docs/pull/955 +[#937]: https://github.com/just-the-docs/just-the-docs/pull/937 + +### New Contributors + +* [@robinpokorny] made their first contribution in [#940] +* [@olgarithms] made their first contribution in [#951] +* [@manuelhenke] made their first contribution in [#941] +* [@JPrevost] made their first contribution in [#950] + +[@robinpokorny]: https://github.com/robinpokorny +[@olgarithms]: https://github.com/olgarithms +[@manuelhenke]: https://github.com/manuelhenke +[@JPrevost]: https://github.com/JPrevost + +## Pre-release v0.4.0.rc1 + +### We're back! + +Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include: + +- The new callouts component +- Allowing pages and collections to coexist on the navigation pane +- New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements +- More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting +- Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color +- More documentation, especially on using custom includes +- Updating core dependencies to stable Ruby versions +- A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way! + +We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know! + +### Trying out pre-release `v0.4.0.rc1` + +Due to the massive scope of these changes, we're making `v0.4.0.rc1` available as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`. + +To use this RC explicitly as a remote theme: + +```yml +remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1 +``` + +To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`: + +```ruby +gem "just-the-docs", "0.4.0.rc1" +``` + +### Staying on `v0.3.3` + +If you're not ready to make the switch, that's alright! If your version of just-the-docs is pinned to `v0.3.3` (i.e. by a `Gemfile.lock` or in `remote_theme`, then there's nothing you need to do. + +If you have not pinned your theme version, you should either: + +1. pin your gem version in your `Gemfile`, like so +```ruby +gem "just-the-docs", "0.3.3" +``` +2. freeze the `remote_theme`, like so +```yml +remote_theme: just-the-docs/just-the-docs@v0.3.3 +``` + +{: .warning } +Use of branches for closed PRs (e.g., [#466], [#578]) is now deprecated, as those branches have been (directly or indirectly) merged, and they may be deleted after the pre-release of `v0.4.0.rc1`. + +### Maintenance + +Internally, our maintainer team has expanded: [Patrick Marsceill][@pmarsceill], the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks! + +The new core team currently consists of [@mattxwang], [@pdmosses], [@skullface], [@dougaitken], and [@max06]. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time! + +[@mattxwang]: https://github.com/mattxwang +[@pdmosses]: https://github.com/pdmosses +[@skullface]: https://github.com/skullface +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 + +### Roadmap + +In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs. + +We're also scoping out medium and long-term projects, and want to keep you in the loop. These include: + +- upgrading to Jekyll 4, and stopping support for Jekyll 3 +- versioned docs - issue [#728] +- improved accessibility - issues [#566], [#870] +- internationalization (i18n) - issue [#59] +- recursive/multi-level navigation - PR [#462] +- toggleable dark mode - issue [#234] + +as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us [on GitHub](https://github.com/just-the-docs/just-the-docs) - any contribution (raising an issue, writing docs, or submitting a PR) is welcome! + +[#728]: https://github.com/just-the-docs/just-the-docs/issues/728 +[#566]: https://github.com/just-the-docs/just-the-docs/issues/566 +[#870]: https://github.com/just-the-docs/just-the-docs/issues/870 +[#59]: https://github.com/just-the-docs/just-the-docs/issues/59 +[#462]: https://github.com/just-the-docs/just-the-docs/pull/462 +[#234]: https://github.com/just-the-docs/just-the-docs/issues/234 + +### Features + +* Added: Combination by [@pdmosses] in [#578] + - Added: dark highlighting in [#463] + - Added: pages and collections in [#448] + - Added: callouts in [#466] + - Fixed: breadcrumb behaviour … by [@AdityaTiwari2102] in [#477] + - Fixed: prevent rake command corrupting search data in [#495] (also listed below) + - Fixed: nested lists in [#496] + - Fixed: set color for search input in [#498] (also listed below) + - Fixed: sites with no child pages (no PR) + - Fixed: TOC/breadcrumbs for multiple collections in [#494] + - Added: collection configuration option `nav_fold` (no PR) + - Fixed: indentation and color for folded collection navigation (no PR) + - Fixed: scroll navigation to show the link to the current page in [#639] + - Fixed: Replace all uses of `absolute_url` by `relative_url`, by [@svrooij] in [#544] +* Added: custom favicon `_includes` by [@burner1024] in [#364] +* Added: set color for search input by [@pdmosses] in [#498] +* Added: search placeholder configuration by [@mattxwang] in [#613] +* Added: 'child_nav_order' front matter to be able to sort navigation pages in reverse by [@jmertic] in [#726] +* Added: `nav_footer_custom` include by [@nathanjessen] in [#474] +* Added: style fixes for jekyll-asciidoc by [@alyssais] in [#829] +* Added: mermaid.js support by [@nascosto] in [#857] +* Added: support for external navigation links by [@SPGoding] in [#876] +* Added: refactor `mermaid` config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` by [@mattxwang] in [#909] +* Fixed: prepend `site.collections_dir` if exists by [@alexsegura] in [#519] +* Fixed: nested task lists (#517) by [@pdmosses] in [#855] +* Fixed: suppress Liquid processing in CSS comments by [@pdmosses] in [#686] +* Fixed: prevent rake command from corrupting search data by [@pdmosses] in [#495] +* Fixed: anchor heading links should be visible on focus by [@jacobhq] in [#846] +* Fixed: add `overflow-x: auto` to `figure.highlight` by [@iridazzle] in [#727] +* Fixed: add `overflow-wrap: word-break` to `body` by [@iridazzle] in [#889] +* Fixed: vertical alignment for consecutive labels by [@Eisverygoodletter] in [#893] +* Fixed: allow links to wrap by [@pdmosses] in [#905] +* Fixed: nav scroll feature and absolute/relative URLs by [@pdmosses] in [#898] + +[#578]: https://github.com/just-the-docs/just-the-docs/pull/578 +[#463]: https://github.com/just-the-docs/just-the-docs/pull/463 +[#448]: https://github.com/just-the-docs/just-the-docs/pull/448 +[#466]: https://github.com/just-the-docs/just-the-docs/pull/466 +[#477]: https://github.com/just-the-docs/just-the-docs/pull/477 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#496]: https://github.com/just-the-docs/just-the-docs/pull/496 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#494]: https://github.com/just-the-docs/just-the-docs/pull/494 +[#639]: https://github.com/just-the-docs/just-the-docs/pull/639 +[#544]: https://github.com/just-the-docs/just-the-docs/pull/544 +[#364]: https://github.com/just-the-docs/just-the-docs/pull/364 +[#498]: https://github.com/just-the-docs/just-the-docs/pull/498 +[#613]: https://github.com/just-the-docs/just-the-docs/pull/613 +[#726]: https://github.com/just-the-docs/just-the-docs/pull/726 +[#474]: https://github.com/just-the-docs/just-the-docs/pull/474 +[#829]: https://github.com/just-the-docs/just-the-docs/pull/829 +[#857]: https://github.com/just-the-docs/just-the-docs/pull/857 +[#876]: https://github.com/just-the-docs/just-the-docs/pull/876 +[#909]: https://github.com/just-the-docs/just-the-docs/pull/909 +[#519]: https://github.com/just-the-docs/just-the-docs/pull/519 +[#855]: https://github.com/just-the-docs/just-the-docs/pull/855 +[#686]: https://github.com/just-the-docs/just-the-docs/pull/686 +[#495]: https://github.com/just-the-docs/just-the-docs/pull/495 +[#846]: https://github.com/just-the-docs/just-the-docs/pull/846 +[#727]: https://github.com/just-the-docs/just-the-docs/pull/727 +[#889]: https://github.com/just-the-docs/just-the-docs/pull/889 +[#893]: https://github.com/just-the-docs/just-the-docs/pull/893 +[#905]: https://github.com/just-the-docs/just-the-docs/pull/905 +[#898]: https://github.com/just-the-docs/just-the-docs/pull/898 + +### Documentation + +* Added: docs on how to break an `ol` by [@pdmosses] in [#856] +* Added: docs for custom includes by [@nathanjessen] in [#806] +* Added: document caveat about variable dependencies by [@waldyrious] in [#555] +* Added: docs on how to use `custom_head` to add a custom favicon by [@UnclassedPenguin] in [#814] +* Fixed: `ol` on `index.md` by [@pmarsceill] in [#778] +* Fixed: image link in Markdown kitchen sink by [@JeffGuKang] in [#221] +* Fixed: images in Markdown kitchen sink by [@dougaitken] in [#782] +* Fixed: clearer label of link to Jekyll quickstart by [@waldyrious] in [#549] +* Fixed: remove extra spaces in component docs by [@MichelleBlanchette] in [#554] +* Fixed: double "your" typo in `index.md` by [@sehilyi] in [#499] +* Fixed: "you" -> "your" typo in `index.md` by [@nathanjessen] in [#473] +* Fixed: spacing in toc example by [@henryiii] in [#835] +* Fixed: typo in `README` on `_config.yml` by [@ivanskodje] in [#891] +* Fixed: missing code fence in navigation structure docs by [@mattxwang] in [#906] + +[#856]: https://github.com/just-the-docs/just-the-docs/pull/856 +[#806]: https://github.com/just-the-docs/just-the-docs/pull/806 +[#555]: https://github.com/just-the-docs/just-the-docs/pull/555 +[#814]: https://github.com/just-the-docs/just-the-docs/pull/814 +[#778]: https://github.com/just-the-docs/just-the-docs/pull/778 +[#221]: https://github.com/just-the-docs/just-the-docs/pull/221 +[#782]: https://github.com/just-the-docs/just-the-docs/pull/782 +[#549]: https://github.com/just-the-docs/just-the-docs/pull/549 +[#554]: https://github.com/just-the-docs/just-the-docs/pull/554 +[#499]: https://github.com/just-the-docs/just-the-docs/pull/499 +[#473]: https://github.com/just-the-docs/just-the-docs/pull/473 +[#835]: https://github.com/just-the-docs/just-the-docs/pull/835 +[#891]: https://github.com/just-the-docs/just-the-docs/pull/891 +[#906]: https://github.com/just-the-docs/just-the-docs/pull/906 + +### Maintenance + +* Added: VScode devcontainer by [@max06] in [#783] +* Added: `webrick` to `Gemfile` by [@mattxwang] in [#799] +* Added: 'This site is powered by Netlify.' to the footer by [@mattxwang] in [#797] +* Updated: new repo path by [@pmarsceill] in [#775] +* Updated: rename `master` -> `main` by [@pmarsceill] in [#776] +* Updated: README by [@pmarsceill] in [#777] +* Updated: Code of Conduct to Contributor Covenant v2.1 by [@mattxwang] in [#790] +* Updated: CI files, Ruby & Node Versions by [@mattxwang] in [#820] +* Updated: Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues by [@mattxwang] in [#821] + +[#783]: https://github.com/just-the-docs/just-the-docs/pull/783 +[#799]: https://github.com/just-the-docs/just-the-docs/pull/799 +[#797]: https://github.com/just-the-docs/just-the-docs/pull/797 +[#775]: https://github.com/just-the-docs/just-the-docs/pull/775 +[#776]: https://github.com/just-the-docs/just-the-docs/pull/776 +[#777]: https://github.com/just-the-docs/just-the-docs/pull/777 +[#790]: https://github.com/just-the-docs/just-the-docs/pull/790 +[#820]: https://github.com/just-the-docs/just-the-docs/pull/820 +[#821]: https://github.com/just-the-docs/just-the-docs/pull/821 + +### Dependencies + +* Upgrade to GitHub-native Dependabot by @dependabot-preview in [#627] +* [Security] Bump y18n from 3.2.1 to 3.2.2 by @dependabot-preview in [#606] +* [Security] Bump hosted-git-info from 2.7.1 to 2.8.9 by @dependabot-preview in [#641] +* [Security] Bump lodash from 4.17.19 to 4.17.21 by @dependabot-preview in [#640] +* [Security] Bump ini from 1.3.5 to 1.3.8 by @dependabot-preview in [#511] +* Bump path-parse from 1.0.6 to 1.0.7 by @dependabot in [#699] +* Bump ajv from 6.10.0 to 6.12.6 by @dependabot in [#766] +* Bump prettier from 2.1.2 to 2.5.1 by @dependabot in [#787] +* Bump prettier from 2.5.1 to 2.6.2 by @dependabot in [#809] +* Bump prettier from 2.6.2 to 2.7.1 by @dependabot in [#864] + +[#627]: https://github.com/just-the-docs/just-the-docs/pull/627 +[#606]: https://github.com/just-the-docs/just-the-docs/pull/606 +[#641]: https://github.com/just-the-docs/just-the-docs/pull/641 +[#640]: https://github.com/just-the-docs/just-the-docs/pull/640 +[#511]: https://github.com/just-the-docs/just-the-docs/pull/511 +[#699]: https://github.com/just-the-docs/just-the-docs/pull/699 +[#766]: https://github.com/just-the-docs/just-the-docs/pull/766 +[#787]: https://github.com/just-the-docs/just-the-docs/pull/787 +[#809]: https://github.com/just-the-docs/just-the-docs/pull/809 +[#864]: https://github.com/just-the-docs/just-the-docs/pull/864 + +### New Contributors + +* [@AdityaTiwari2102] made their first contribution in [#477] +* [@svrooij] made their first contribution in [#544] +* [@alexsegura] made their first contribution in [#519] +* [@burner1024] made their first contribution in [#364] +* [@JeffGuKang] made their first contribution in [#221] +* [@dougaitken] made their first contribution in [#782] +* [@max06] made their first contribution in [#783] +* [@sehilyi] made their first contribution in [#499] +* [@nathanjessen] made their first contribution in [#473] +* [@waldyrious] made their first contribution in [#549] +* [@MichelleBlanchette] made their first contribution in [#554] +* [@henryiii] made their first contribution in [#835] +* [@jmertic] made their first contribution in [#726] +* [@jacobhq] made their first contribution in [#846] +* [@UnclassedPenguin] made their first contribution in [#814] +* [@alyssais] made their first contribution in [#829] +* [@nascosto] made their first contribution in [#857] +* [@SPGoding] made their first contribution in [#876] +* [@iridazzle] made their first contribution in [#727] +* [@ivanskodje] made their first contribution in [#891] +* [@Eisverygoodletter] made their first contribution in [#893] + +[@AdityaTiwari2102]: https://github.com/AdityaTiwari2102 +[@svrooij]: https://github.com/svrooij +[@alexsegura]: https://github.com/alexsegura +[@burner1024]: https://github.com/burner1024 +[@JeffGuKang]: https://github.com/JeffGuKang +[@dougaitken]: https://github.com/dougaitken +[@max06]: https://github.com/max06 +[@sehilyi]: https://github.com/sehilyi +[@nathanjessen]: https://github.com/nathanjessen +[@waldyrious]: https://github.com/waldyrious +[@MichelleBlanchette]: https://github.com/MichelleBlanchette +[@henryiii]: https://github.com/henryiii +[@jmertic]: https://github.com/jmertic +[@jacobhq]: https://github.com/jacobhq +[@UnclassedPenguin]: https://github.com/UnclassedPenguin +[@alyssais]: https://github.com/alyssais +[@nascosto]: https://github.com/nascosto +[@SPGoding]: https://github.com/SPGoding +[@iridazzle]: https://github.com/iridazzle +[@ivanskodje]: https://github.com/ivanskodje +[@Eisverygoodletter]: https://github.com/Eisverygoodletter + +**Full Changelog**: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1 + +[@pmarsceill]: https://github.com/pmarsceill + +## v0.3.3 + +### 🚀 Features + +- Add custom header and footer include files @CodeSandwich (#334) + +### 🐛 Bug Fixes + +- Limit the effect of `nav_exclude` to the main navigation @pdmosses (#443) +- Update normalize.scss @pdmosses (#444) +- Update code.scss @pdmosses (#445) +- Fix list alignment @pdmosses (#446) + +### 🧰 Maintenance + +- Bump stylelint-config-primer from 9.0.0 to 9.2.1 @dependabot-preview (#451) +- Bump stylelint from 13.6.1 to 13.7.2 @dependabot-preview (#440) +- Bump @primer/css from 15.1.0 to 15.2.0 @dependabot-preview (#436) +- Bump prettier from 2.1.1 to 2.1.2 @dependabot-preview (#429) + +## v0.3.2 + +### Changes + +- Safe page sorting @pdmosses (#411) +- v0.3.2 @pmarsceill (#388) + +### 🚀 Features + +- make font-sizes sass variables so they can be changed @pdebruic (#361) +- run the site locally inside docker container @fogfish (#398) +- Feature/doc collections @SgtSilvio (#379) +- Adjust dl layout @pdmosses (#401) + +### 🐛 Bug Fixes + +- Add site.gh_edit_source to "Edit this page on GitHub" link @mrfleap (#418) +- Inhibit text-transform for code in h4 @pdmosses (#404) +- Fix native font stack precedence issue on Windows systems. @hvianna (#331) +- Support for the linenos option on highlighted code @pdmosses (#375) +- Update anchor_headings.html @pdmosses (#399) +- Fix https @marksie1988 (#359) + +### 🧰 Maintenance + +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#427) +- Bump prettier from 2.0.5 to 2.1.1 @dependabot-preview (#419) +- [Security] Bump lodash from 4.17.15 to 4.17.19 @dependabot-preview (#389) +- Bump @primer/css from 14.4.0 to 15.1.0 @dependabot-preview (#402) +- Bump lodash from 4.17.15 to 4.17.19 @dependabot (#384) +- Bump @primer/css from 14.4.0 to 15.0.0 @dependabot-preview (#371) + + +## v0.3.1 + +### Changes + +### 🐛 Bug Fixes + +- Improve accessibility by adding label to Anchor links. @mscoutermarsh (#376) + +### 🧰 Maintenance + +- Remove collapsible TOC on nav doc @pmarsceill (#368) +- Pdmosses collapsible toc @pmarsceill (#367) + + +## v0.3.0 + +### Changes + +- v0.2.9 @pmarsceill (#306) + +### 🚀 Features + +- Add print styles @pmarsceill (#362) +- Navigation improvements and search sections @SgtSilvio (#352) + +### 🐛 Bug Fixes + +- Remove constraint with jekyll 4.1.0 @PierrickMartos (#348) + +### 🧰 Maintenance + +- Bump version numbers @pmarsceill (#360) +- Bump stylelint from 13.3.3 to 13.6.1 @dependabot-preview (#343) +- Bump stylelint-config-prettier from 8.0.1 to 8.0.2 @dependabot-preview (#349) + + +## v0.2.9 + +### Bug fixes +- Horizontal Alignment #103 @pmarsceill +- Code snippet in headers do not inherit font size #140 @pmarsceill +- Fix duplicated title and description tags #294 @iefserge +- Update nav.html for handling nav_exclude #282 @blawqchain +- Fix duplicate entries in nav.html and default.html #239 @KasparEtter +- Don't show pages with no title (e.g. redirects in nav) https://github.com/pmarsceill/just-the-docs/pull/295/commits/672de29f2e332a9350af7237e4fb6693c848989e @SgtSilvio +- [SEARCH RAKE] Fix search generator #319 @RoiArthurB + +### Enhancements +- Improvement/custom themes #186 @SgtSilvio +- feat: adds "edit this page" and "page last modified" to footer #217 @malsf21 +- feat: adds option to open aux links in new tab #229 @malsf21 +- Default nav order #236 @pdmosses +- Enable IP anonymization in Google Analytics (GDPR) #250 @r-brown + +closes #240 #308 #266 #140 #103 + +## v0.2.8 + +### Bugfixes +- bugfix in search.rake #218 @tiaitsch85 + +### Dependency and security updates: + +- Update jekyll requirement from ~> 3.8.5 to >= 3.8.5, < 4.1.0 #197 @dependabot-preview +- Update rake requirement from ~> 12.3.1 to >= 12.3.1, < 13.1.0 #227 @dependabot-preview +- Bump stylelint-config-primer from 8.0.0 to 9.0.0 #247 @dependabot-preview +- Update bundler requirement from ~> 2.0.1 to ~> 2.1.4 #268 @dependabot-preview +- Bump @primer/css from 12.7.0 to 14.3.0 #296 @dependabot-preview + +### Operations + +- Update CI to test multiple versions of Jekyll +- Update CI to check the rake command that builds the search file + +fixes #291 #256 #293 #177 + +## v0.2.7 + +### Bugs fixed +- Anchor headings are now displayed on hover, not only on heading hover +- Deduplicated anchor heading svg +- If last page of `site.html_pages` was excluded from search, search json breaks +- Config variable should be `blanklines` not `blank_lines` for html compression +- `list-style-none` does not hide bullets on `ul` + +### Enhancements +- Summary for child pages appears in generated TOC +- Site logo configuration supported replacing title text with image +- Allow custom CSS overrides (new scss partial at the end of the cascade) separate from variable overrides. +- Configuration around search strings added to allow search for hyphenated words + +### Maintenance +- Update docs to suggest using index.md as section page filename +- Bump @primer/css from 12.6.0 to 12.7.0 +- Bump mixin-deep from 1.3.1 to 1.3.2 +- Bump stylelint-config-primer from 7.0.1 to 8.0.0 + +### PR included +- #98 by @stefanoborini Introduces the possibility for a summary in the table of contents +- #141 by @ghabs Fix trailing comma bug in search-data.json +- #153 by @jacobherrington Change button copy on theme preview +- #181 by @m3nu Recommend using index.md as parent page for sections +- #183 by @SgtSilvio Improve heading anchors +- #187 by @SgtSilvio Improvement/site logo +- #200 Bump mixin-deep from 1.3.1 to 1.3.2 +- #203 by @pdmosses Search config +- #205 by @pdmosses Fix blank_lines var to blanklines in config.yml +- #206 by @iamcarrico Allow for custom overrides by the user +- #208 Bump @primer/css from 12.6.0 to 12.7.0 +- #213 Bump mixin-deep from 1.3.1 to 1.3.2 +- #214 Bump stylelint-config-primer from 7.0.1 to 8.0.0 +- #215 Bump @primer/css from 12.6.0 to 12.7.0 + +## v0.2.6 + +### Bugs fixed +- Google Analytics tag has been updated #162 +- ~BaseURL has been modified #109~ Reverted -- seems the existing implementation worked +- Titles can now wrap fixes #106 + +### Enhancements +- Search now displays content preview #135 +- Custom footer content added #179 +- Now using GitHub Actions for CI #170 + +### Maintenance +- lunrjs upgraded #135 +- Nav generation is optimized #159 +- Stylelint upgrade #143 +- Stylelint config primer upgrade #149 +- Lodash upgrade #160 + +### PR included +~#109 by @daviddarnes - Fix baseurl link~ Reverted +#135 by @SgtSilvio - Upgrades lunr.js, improves search UI, adds heading anchors +#152 by @yavorg - Improves syntax highlighting for js readablity +#159 by @julienduchesne - Optimizes nav generation +#162 by @nergmada - Modifies the google analytics code to match the new tags used by GA + + +## v0.2.5 + +### Bugs fixed + +- Duplicate title tag when Jekyll SEO Plugin gem is used #125 #126 + +### Enhancements + +- Favicon support added #118 + +### Maintenance +- Bump stylelint-config-primer from 6.0.0 to 7.0.0 #123 +- Bump @primer/css from 12.2.3 to 12.3.1 #129 +- Add workflow to publish to GPR +- Fix workflow to publish to Ruby Gems + +## v0.2.4 + +### Bugs + +- #102 Remove unnecessary console.log() @JoeNyland +- #97 Import custom Sass variable overrides before default variables are defined @montchr and @ptvandi + +### Additions +- #117 Add links to docs for setting up GH pages locally @gnarea +- #95 Add SEO and 'lang' param for `_config` @gebeto + +## v0.2.3 + +### Enhancements +- Adds ability to use Google Analytics tracking by @pmarsceill + +### Bug fixes +- Fixes 404 error for "/assets/js//search-data.json" by @stephenedmondson +- Fixes #80 Single quotes in the string were unescaped and ruby attempted variable substitution of amp within it (which failed) by @novelistparty +- Fixes bug that would only show 2 or more search results (not one) by @ilivewithian +- Fixes a typo on the layout example by @woernfl +- Fixes #78 Page scroll position too far down on load by @pmarsceill +- Fixds ability to nest ul in ol without breaking style or counters + +### Dependency updates +- Bumps stylelint dependency from 9.9.0 to 9.10.1 + +## v0.2.2 + +- Bumps stylelint-config-primer to 3.0.1 #44 +- Bumps bundler req to 2.0.1 #61 +- Adds custom 404 page +- Excludes package-lock.json from jekyll build #47 +- Fixes keyboard scrolling / focus #48 +- Adds ARIA roles to navigation elements +- Adds support for optional page description metadata (if present in yaml front matter) +- Addresses some issues with search in #46 +- Option to hide TOC on parent pages if turned off in page's YAML front matter #30 +- Option to suppress an item from being indexed by search if present in page's YAML front matter #32 + +## v0.2.1 + +This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version. + +## v0.2.0 + +Adds: +- Dark mode via `color_scheme` parameter +- Ability to exclude a page from the main nav with `nav_exclude` parameter closes #21 +- Ability for create children of children pages (3 nav levels) closes #25 + +Changes: +- Permalink structure for tiered navigation has been updated +- Some colors have been updated for consistency / accessibility + +## v0.1.6 + +### Added + +- Support for task list styles #19 +- Configuration docs +- Configuration option to enable / disable search +- Normalize.scss dependency pulled into project #16 # + +### Fixed + +- Layout bug in navigation #17 + +## v0.1.5 + +Major changes: + +- Fixed bug where the rake task would fail when the assets/js directory didn't exist + +## v0.1.4 + +Major changes: +- Adds Rake as a runtime dependency +- Definition list styled +- Sidebar and support cleaned up for smaller screen support +- Updated some stale docs + +## v0.1.3 + +Major changes: +- Fix path problems, typos, and general clean-up for OSS. + +## v0.1.2 + +Fix paths when deployed to gh-pages + +## v0.1.1 + +Major updates: +- Adds search to mobile nav +- Pulls footer to bottom of the page on mobile (not hidden in nav) + +Minor updates: +- Cleans up h1 typography spacing \ No newline at end of file diff --git a/_config.yml b/_config.yml index faa6eaa..7cffdfa 100644 --- a/_config.yml +++ b/_config.yml @@ -1,8 +1,61 @@ -title: Just the Docs Template -description: A starter template for a Jeykll site using the Just the Docs theme! +title: Documentazione Transit Café +description: Portale di documentazione del Transit Café theme: just-the-docs -url: https://just-the-docs.github.io +url: https://5tsrl.github.io/cafe-docs/ +defaults: + - scope: + path: "pages" # an empty string here means all files in the project + type: "pages" + values: + layout: "default" + + + +aux_links_new_tab: true aux_links: - Template Repository: https://github.com/just-the-docs/just-the-docs-template + Cafe Repository: https://github.com/5Tsrl/cafe-ui + +# Set a path/url to a logo that will be displayed instead of the title +logo: "/assets/cafe150.png" + +# Set a path/url to a favicon that will be displayed by the browser +favicon_ico: "/assets/favicon.ico" + +nav_enabled: true + + +# Footer content +# appears at the bottom of every page's main content +# Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust markup / liquid-based content. +footer_content: "Copyright © 5T srl" + +# Footer last edited timestamp +last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/5Tsrl/cafe-docs" # the github URL for your repo +gh_edit_branch: "main" # the branch that your docs is served from +# gh_edit_source: docs # the source that your files originate from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately + +callouts_level: quiet # or loud +callouts: + highlight: + color: yellow + important: + title: Important + color: blue + new: + title: New + color: green + note: + title: Note + color: purple + warning: + title: Warning + color: red diff --git a/assets/cafe.png b/assets/cafe.png new file mode 100644 index 0000000..4482dcf Binary files /dev/null and b/assets/cafe.png differ diff --git a/assets/cafe150.png b/assets/cafe150.png new file mode 100644 index 0000000..cf0cb4d Binary files /dev/null and b/assets/cafe150.png differ diff --git a/assets/favicon.ico b/assets/favicon.ico new file mode 100644 index 0000000..4492b4e Binary files /dev/null and b/assets/favicon.ico differ diff --git a/img/actions.png b/img/actions.png new file mode 100644 index 0000000..0415a04 Binary files /dev/null and b/img/actions.png differ diff --git a/img/add-fare-zone.png b/img/add-fare-zone.png new file mode 100644 index 0000000..c1ea0fe Binary files /dev/null and b/img/add-fare-zone.png differ diff --git a/img/add-snapshot.png b/img/add-snapshot.png new file mode 100644 index 0000000..0a10b95 Binary files /dev/null and b/img/add-snapshot.png differ diff --git a/img/add-stop.png b/img/add-stop.png new file mode 100644 index 0000000..e1eb945 Binary files /dev/null and b/img/add-stop.png differ diff --git a/img/agency-detail.png b/img/agency-detail.png new file mode 100644 index 0000000..882821a Binary files /dev/null and b/img/agency-detail.png differ diff --git a/img/agency-mandatory-fields.png b/img/agency-mandatory-fields.png new file mode 100644 index 0000000..9637554 Binary files /dev/null and b/img/agency-mandatory-fields.png differ diff --git a/img/auth0-token-generator.png b/img/auth0-token-generator.png new file mode 100644 index 0000000..0acae70 Binary files /dev/null and b/img/auth0-token-generator.png differ diff --git a/img/available-snapshots.png b/img/available-snapshots.png new file mode 100644 index 0000000..844be00 Binary files /dev/null and b/img/available-snapshots.png differ diff --git a/img/available-versions.png b/img/available-versions.png new file mode 100644 index 0000000..8709724 Binary files /dev/null and b/img/available-versions.png differ diff --git a/img/blocked-feed.png b/img/blocked-feed.png new file mode 100644 index 0000000..d020652 Binary files /dev/null and b/img/blocked-feed.png differ diff --git a/img/calendar-detail.png b/img/calendar-detail.png new file mode 100644 index 0000000..efc547d Binary files /dev/null and b/img/calendar-detail.png differ diff --git a/img/calendar-legend.png b/img/calendar-legend.png new file mode 100644 index 0000000..010b5fb Binary files /dev/null and b/img/calendar-legend.png differ diff --git a/img/create-feed.png b/img/create-feed.png new file mode 100644 index 0000000..6014144 Binary files /dev/null and b/img/create-feed.png differ diff --git a/img/create-project.png b/img/create-project.png new file mode 100644 index 0000000..348b7d3 Binary files /dev/null and b/img/create-project.png differ diff --git a/img/create-user.png b/img/create-user.png new file mode 100644 index 0000000..7f899b8 Binary files /dev/null and b/img/create-user.png differ diff --git a/img/create-version-feed.png b/img/create-version-feed.png new file mode 100644 index 0000000..0201572 Binary files /dev/null and b/img/create-version-feed.png differ diff --git a/img/create-version.png b/img/create-version.png new file mode 100644 index 0000000..5bb12c0 Binary files /dev/null and b/img/create-version.png differ diff --git a/img/delete-node.png b/img/delete-node.png new file mode 100644 index 0000000..a1577d9 Binary files /dev/null and b/img/delete-node.png differ diff --git a/img/download-calendar-string.png b/img/download-calendar-string.png new file mode 100644 index 0000000..988edeb Binary files /dev/null and b/img/download-calendar-string.png differ diff --git a/img/edit-calendars.png b/img/edit-calendars.png new file mode 100644 index 0000000..e49968d Binary files /dev/null and b/img/edit-calendars.png differ diff --git a/img/edit-fare-rules.png b/img/edit-fare-rules.png new file mode 100644 index 0000000..2aaf49b Binary files /dev/null and b/img/edit-fare-rules.png differ diff --git a/img/edit-fares.png b/img/edit-fares.png new file mode 100644 index 0000000..8794d5d Binary files /dev/null and b/img/edit-fares.png differ diff --git a/img/edit-frequencies.png b/img/edit-frequencies.png new file mode 100644 index 0000000..24ce993 Binary files /dev/null and b/img/edit-frequencies.png differ diff --git a/img/edit-pattern-geometry.png b/img/edit-pattern-geometry.png new file mode 100644 index 0000000..701af36 Binary files /dev/null and b/img/edit-pattern-geometry.png differ diff --git a/img/edit-patterns.png b/img/edit-patterns.png new file mode 100644 index 0000000..1c8dfcd Binary files /dev/null and b/img/edit-patterns.png differ diff --git a/img/edit-routes.png b/img/edit-routes.png new file mode 100644 index 0000000..c12c461 Binary files /dev/null and b/img/edit-routes.png differ diff --git a/img/edit-stops.png b/img/edit-stops.png new file mode 100644 index 0000000..a597f9c Binary files /dev/null and b/img/edit-stops.png differ diff --git a/img/edit-timetables.png b/img/edit-timetables.png new file mode 100644 index 0000000..7659ec8 Binary files /dev/null and b/img/edit-timetables.png differ diff --git a/img/editor-from-scratch.png b/img/editor-from-scratch.png new file mode 100644 index 0000000..71cb638 Binary files /dev/null and b/img/editor-from-scratch.png differ diff --git a/img/export-gtfs.png b/img/export-gtfs.png new file mode 100644 index 0000000..ed625e9 Binary files /dev/null and b/img/export-gtfs.png differ diff --git a/img/export-shp.png b/img/export-shp.png new file mode 100644 index 0000000..42d91e9 Binary files /dev/null and b/img/export-shp.png differ diff --git a/img/feed-info.png b/img/feed-info.png new file mode 100644 index 0000000..9932e29 Binary files /dev/null and b/img/feed-info.png differ diff --git a/img/feed-overview.png b/img/feed-overview.png new file mode 100644 index 0000000..2761e9b Binary files /dev/null and b/img/feed-overview.png differ diff --git a/img/feed-profile.png b/img/feed-profile.png new file mode 100644 index 0000000..ae758e3 Binary files /dev/null and b/img/feed-profile.png differ diff --git a/img/feed-settings.png b/img/feed-settings.png new file mode 100644 index 0000000..0a8a959 Binary files /dev/null and b/img/feed-settings.png differ diff --git a/img/feed-version-navigator.png b/img/feed-version-navigator.png new file mode 100644 index 0000000..da23dca Binary files /dev/null and b/img/feed-version-navigator.png differ diff --git a/img/graph-manager.png b/img/graph-manager.png new file mode 100644 index 0000000..083cc6d Binary files /dev/null and b/img/graph-manager.png differ diff --git a/img/lines-manager.png b/img/lines-manager.png new file mode 100644 index 0000000..74ab439 Binary files /dev/null and b/img/lines-manager.png differ diff --git a/img/load-version-editor.png b/img/load-version-editor.png new file mode 100644 index 0000000..627fdd3 Binary files /dev/null and b/img/load-version-editor.png differ diff --git a/img/load-version.png b/img/load-version.png new file mode 100644 index 0000000..9179034 Binary files /dev/null and b/img/load-version.png differ diff --git a/img/make-snapshot.png b/img/make-snapshot.png new file mode 100644 index 0000000..785c94d Binary files /dev/null and b/img/make-snapshot.png differ diff --git a/img/manager-read-only.png b/img/manager-read-only.png new file mode 100644 index 0000000..2d3692b Binary files /dev/null and b/img/manager-read-only.png differ diff --git a/img/normalize-stop-time.png b/img/normalize-stop-time.png new file mode 100644 index 0000000..a50df19 Binary files /dev/null and b/img/normalize-stop-time.png differ diff --git a/img/overview-data-validation.png b/img/overview-data-validation.png new file mode 100644 index 0000000..ce4ddf0 Binary files /dev/null and b/img/overview-data-validation.png differ diff --git a/img/overview-data.png b/img/overview-data.png new file mode 100644 index 0000000..45190fa Binary files /dev/null and b/img/overview-data.png differ diff --git a/img/overview-editor.png b/img/overview-editor.png new file mode 100644 index 0000000..ec7d8e9 Binary files /dev/null and b/img/overview-editor.png differ diff --git a/img/overview-manager.png b/img/overview-manager.png new file mode 100644 index 0000000..1844c89 Binary files /dev/null and b/img/overview-manager.png differ diff --git a/img/overview-progr-km.png b/img/overview-progr-km.png new file mode 100644 index 0000000..1d41fc4 Binary files /dev/null and b/img/overview-progr-km.png differ diff --git a/img/overview-project.png b/img/overview-project.png new file mode 100644 index 0000000..d15e9dc Binary files /dev/null and b/img/overview-project.png differ diff --git a/img/overview-tool.png b/img/overview-tool.png new file mode 100644 index 0000000..cf153a9 Binary files /dev/null and b/img/overview-tool.png differ diff --git a/img/password-reset-logged-in.png b/img/password-reset-logged-in.png new file mode 100644 index 0000000..9f6c004 Binary files /dev/null and b/img/password-reset-logged-in.png differ diff --git a/img/password-reset-logged-out.png b/img/password-reset-logged-out.png new file mode 100644 index 0000000..6e336dc Binary files /dev/null and b/img/password-reset-logged-out.png differ diff --git a/img/pattern-add-stop.png b/img/pattern-add-stop.png new file mode 100644 index 0000000..3d495de Binary files /dev/null and b/img/pattern-add-stop.png differ diff --git a/img/pattern-insert-stop.png b/img/pattern-insert-stop.png new file mode 100644 index 0000000..cd44ebe Binary files /dev/null and b/img/pattern-insert-stop.png differ diff --git a/img/pattern-manager.png b/img/pattern-manager.png new file mode 100644 index 0000000..6ebe4f0 Binary files /dev/null and b/img/pattern-manager.png differ diff --git a/img/pattern-popup.png b/img/pattern-popup.png new file mode 100644 index 0000000..f6cad2b Binary files /dev/null and b/img/pattern-popup.png differ diff --git a/img/pattern-shape-panel.png b/img/pattern-shape-panel.png new file mode 100644 index 0000000..fad028f Binary files /dev/null and b/img/pattern-shape-panel.png differ diff --git a/img/pattern-stop-order.png b/img/pattern-stop-order.png new file mode 100644 index 0000000..048d121 Binary files /dev/null and b/img/pattern-stop-order.png differ diff --git a/img/pattern-stop-remove.png b/img/pattern-stop-remove.png new file mode 100644 index 0000000..d4ae4ec Binary files /dev/null and b/img/pattern-stop-remove.png differ diff --git a/img/pattern-stop-toolbar.png b/img/pattern-stop-toolbar.png new file mode 100644 index 0000000..2c5fe91 Binary files /dev/null and b/img/pattern-stop-toolbar.png differ diff --git a/img/pattern-toolbar.png b/img/pattern-toolbar.png new file mode 100644 index 0000000..0816e1a Binary files /dev/null and b/img/pattern-toolbar.png differ diff --git a/img/pattern-version-confirm.png b/img/pattern-version-confirm.png new file mode 100644 index 0000000..47199a5 Binary files /dev/null and b/img/pattern-version-confirm.png differ diff --git a/img/project-feed-list.png b/img/project-feed-list.png new file mode 100644 index 0000000..2761e9b Binary files /dev/null and b/img/project-feed-list.png differ diff --git a/img/project-profile.png b/img/project-profile.png new file mode 100644 index 0000000..40e1853 Binary files /dev/null and b/img/project-profile.png differ diff --git a/img/project-vs-feed.PNG b/img/project-vs-feed.PNG new file mode 100644 index 0000000..8ed14ab Binary files /dev/null and b/img/project-vs-feed.PNG differ diff --git a/img/public-portal.png b/img/public-portal.png new file mode 100644 index 0000000..f80ea94 Binary files /dev/null and b/img/public-portal.png differ diff --git a/img/quick-access-toolbar-feed-source.png b/img/quick-access-toolbar-feed-source.png new file mode 100644 index 0000000..810c21c Binary files /dev/null and b/img/quick-access-toolbar-feed-source.png differ diff --git a/img/quick-access-toolbar.png b/img/quick-access-toolbar.png new file mode 100644 index 0000000..6502209 Binary files /dev/null and b/img/quick-access-toolbar.png differ diff --git a/img/read-only.png b/img/read-only.png new file mode 100644 index 0000000..0b90772 Binary files /dev/null and b/img/read-only.png differ diff --git a/img/report-corse-pdf.png b/img/report-corse-pdf.png new file mode 100644 index 0000000..f9ecb2b Binary files /dev/null and b/img/report-corse-pdf.png differ diff --git a/img/report-corse.png b/img/report-corse.png new file mode 100644 index 0000000..e5e9313 Binary files /dev/null and b/img/report-corse.png differ diff --git a/img/report-linee-pdf.png b/img/report-linee-pdf.png new file mode 100644 index 0000000..a44439c Binary files /dev/null and b/img/report-linee-pdf.png differ diff --git a/img/report-linee.png b/img/report-linee.png new file mode 100644 index 0000000..893260a Binary files /dev/null and b/img/report-linee.png differ diff --git a/img/report-orari-pdf.png b/img/report-orari-pdf.png new file mode 100644 index 0000000..cfe3ae1 Binary files /dev/null and b/img/report-orari-pdf.png differ diff --git a/img/report-orari.png b/img/report-orari.png new file mode 100644 index 0000000..6773e60 Binary files /dev/null and b/img/report-orari.png differ diff --git a/img/reports.png b/img/reports.png new file mode 100644 index 0000000..fb7a707 Binary files /dev/null and b/img/reports.png differ diff --git a/img/schedule-exception.png b/img/schedule-exception.png new file mode 100644 index 0000000..b656ec5 Binary files /dev/null and b/img/schedule-exception.png differ diff --git a/img/schedule-toolbar.png b/img/schedule-toolbar.png new file mode 100644 index 0000000..422693b Binary files /dev/null and b/img/schedule-toolbar.png differ diff --git a/img/select-trips.png b/img/select-trips.png new file mode 100644 index 0000000..1bcdaec Binary files /dev/null and b/img/select-trips.png differ diff --git a/img/settings-osserva.png b/img/settings-osserva.png new file mode 100644 index 0000000..201db64 Binary files /dev/null and b/img/settings-osserva.png differ diff --git a/img/shape-shadow.png b/img/shape-shadow.png new file mode 100644 index 0000000..9b1739c Binary files /dev/null and b/img/shape-shadow.png differ diff --git a/img/snapshot-line.png b/img/snapshot-line.png new file mode 100644 index 0000000..1625f4a Binary files /dev/null and b/img/snapshot-line.png differ diff --git a/img/snapshot-toolbar.png b/img/snapshot-toolbar.png new file mode 100644 index 0000000..c52ed87 Binary files /dev/null and b/img/snapshot-toolbar.png differ diff --git a/img/stops-manager.png b/img/stops-manager.png new file mode 100644 index 0000000..3e9dfc9 Binary files /dev/null and b/img/stops-manager.png differ diff --git a/img/summary-feed.png b/img/summary-feed.png new file mode 100644 index 0000000..1844c89 Binary files /dev/null and b/img/summary-feed.png differ diff --git a/img/timetable-selector.png b/img/timetable-selector.png new file mode 100644 index 0000000..f400d8f Binary files /dev/null and b/img/timetable-selector.png differ diff --git a/img/timetables-manager.png b/img/timetables-manager.png new file mode 100644 index 0000000..d59ef12 Binary files /dev/null and b/img/timetables-manager.png differ diff --git a/img/trip-duplica.png b/img/trip-duplica.png new file mode 100644 index 0000000..f25ffc2 Binary files /dev/null and b/img/trip-duplica.png differ diff --git a/img/trip-version.png b/img/trip-version.png new file mode 100644 index 0000000..f6feb91 Binary files /dev/null and b/img/trip-version.png differ diff --git a/img/upload-feed.png b/img/upload-feed.png new file mode 100644 index 0000000..b5511e0 Binary files /dev/null and b/img/upload-feed.png differ diff --git a/img/upload-shp.png b/img/upload-shp.png new file mode 100644 index 0000000..b3a8117 Binary files /dev/null and b/img/upload-shp.png differ diff --git a/img/upload-zip-shp.png b/img/upload-zip-shp.png new file mode 100644 index 0000000..21e2934 Binary files /dev/null and b/img/upload-zip-shp.png differ diff --git a/img/user-admin-detail.png b/img/user-admin-detail.png new file mode 100644 index 0000000..f80e215 Binary files /dev/null and b/img/user-admin-detail.png differ diff --git a/img/user-admin.png b/img/user-admin.png new file mode 100644 index 0000000..fbc5e3b Binary files /dev/null and b/img/user-admin.png differ diff --git a/img/user-profile.png b/img/user-profile.png new file mode 100644 index 0000000..da1c679 Binary files /dev/null and b/img/user-profile.png differ diff --git a/img/version-pattern.png b/img/version-pattern.png new file mode 100644 index 0000000..821ac75 Binary files /dev/null and b/img/version-pattern.png differ diff --git a/img/version-trips.png b/img/version-trips.png new file mode 100644 index 0000000..570652b Binary files /dev/null and b/img/version-trips.png differ diff --git a/img/version-union.png b/img/version-union.png new file mode 100644 index 0000000..f966d41 Binary files /dev/null and b/img/version-union.png differ diff --git a/img/version-vs-snapshots-editor.png b/img/version-vs-snapshots-editor.png new file mode 100644 index 0000000..f9dac97 Binary files /dev/null and b/img/version-vs-snapshots-editor.png differ diff --git a/img/video-aggiunta-rimozione-fermate-percorso.png b/img/video-aggiunta-rimozione-fermate-percorso.png new file mode 100644 index 0000000..50a4ab6 Binary files /dev/null and b/img/video-aggiunta-rimozione-fermate-percorso.png differ diff --git a/img/video-creazione-calendario.png b/img/video-creazione-calendario.png new file mode 100644 index 0000000..f06dad1 Binary files /dev/null and b/img/video-creazione-calendario.png differ diff --git a/img/video-creazione-linea.png b/img/video-creazione-linea.png new file mode 100644 index 0000000..4180892 Binary files /dev/null and b/img/video-creazione-linea.png differ diff --git a/img/video-creazione-percorso.png b/img/video-creazione-percorso.png new file mode 100644 index 0000000..01416b2 Binary files /dev/null and b/img/video-creazione-percorso.png differ diff --git a/img/video-gestione-corse.png b/img/video-gestione-corse.png new file mode 100644 index 0000000..1ddaae2 Binary files /dev/null and b/img/video-gestione-corse.png differ diff --git a/img/video-inserimento-corsa.png b/img/video-inserimento-corsa.png new file mode 100644 index 0000000..2e5e5ec Binary files /dev/null and b/img/video-inserimento-corsa.png differ diff --git a/img/video-modifica-percorso.png b/img/video-modifica-percorso.png new file mode 100644 index 0000000..1e459ee Binary files /dev/null and b/img/video-modifica-percorso.png differ diff --git a/img/video-snapshot-versioni.png b/img/video-snapshot-versioni.png new file mode 100644 index 0000000..4bb8655 Binary files /dev/null and b/img/video-snapshot-versioni.png differ diff --git a/img/video-versionamento-percorso.png b/img/video-versionamento-percorso.png new file mode 100644 index 0000000..5eded8c Binary files /dev/null and b/img/video-versionamento-percorso.png differ diff --git a/img/view-all-stops.png b/img/view-all-stops.png new file mode 100644 index 0000000..814255e Binary files /dev/null and b/img/view-all-stops.png differ diff --git a/index.md b/index.md index ca0c545..61aaa90 100644 --- a/index.md +++ b/index.md @@ -1,35 +1,21 @@ --- title: Home layout: home +nav_order: 1 +description: "Transit Café è uno strumento web gestire feed GTFS." +permalink: / --- -This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details. +# Transit Café -If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages. +Transit Café è uno strumento web per creare, gestire, validare e pubblicare dati del trasporto pubblico, in particolare dati utilizzati nel PEA (Programma di Esercizio Aziendale) e nel formato GTFS (General Transit Feed Specification). -More specifically, the created site: +![screenshot](img/public-portal.png) -- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem -- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages +Nelle pagine seguenti saranno illustrate le funzioni del Transit Café. +Per i dettagli si rimanda alla lista dei contenuti disponibili nella parte sinistra della pagina. -Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. +Visita la [pagina di accesso a Transit Café](https://cafe.5t.torino.it) per entrare nella piattaforma. -[Browse our documentation][Just the Docs] to learn more about how to use this theme. -To get started with creating a site, simply: - -1. click "[use this template]" to create a GitHub repository -2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions - -If you want to maintain your docs in the `docs` directory of an existing project repo, see [Hosting your docs from an existing project repo](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README. - ----- - -[^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). - -[Just the Docs]: https://just-the-docs.github.io/just-the-docs/ -[GitHub Pages]: https://docs.github.com/en/pages -[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md -[Jekyll]: https://jekyllrb.com -[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ -[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate +Per richieste di supporto nell'utilizzo dello strumento contattare cafe@5t.torino.it. diff --git a/pages/appendici/appendix-cafe-summary.md b/pages/appendici/appendix-cafe-summary.md new file mode 100644 index 0000000..da31c79 --- /dev/null +++ b/pages/appendici/appendix-cafe-summary.md @@ -0,0 +1,54 @@ +--- +title: Glossario dei termini +parent: Appendici +nav_order: 1 +--- + +# 2- Glossario dei termini + +Di seguito sono riportate alcune parole chiave per l'utilizzo di Transit Café. + +##### Progetto: +- è una raccolta di feed e relativi versionamenti; +- può rappresentare una determinata area geografica e contenere tutti i contratti di servizio attivi nell'area; +- ha associata l'icona di una cartella. + + +##### Feed: +- può essere identificato con un contratto di esercizio del PEA; +- può contenere più versioni della stessa base dati, +- viene visualizzato nel modulo manager; +- è modificabile nel modulo editor. + + +##### Manager: + +Il modulo Manager si occupa della gestione ed analisi dei feed e di tutte le informazioni ad essi correlate e contiene: +- navigatore di versioni e snapshot; +- periodo di validità del feed; +- informazioni su fermate, linee, percorsi, orari; +- reportistica. + + +##### Editor: + +Il modulo Editor è lo strumento cartografico per la modifica dei dati e permette di: +- modificare, visualizzare e disegnare le linee ed i percorsi; +- modificare la geometria del percorso di una linea con un instradamento automatico o in modalità manuale; +- versionare il dato; +- gestire gli orari e i calendari/frequenze. + + +##### Snapshot: +- è una versione "di lavoro" di un set di dati; +- rappresenta un punto di salvataggio; +- può essere esportato o usato come punto di partenza per modifiche future; +- è associato al simbolo di una fotocamera; +- può essere modifica nel modulo editor. + + +##### Versione: +- rappresenta una variante contrattuale della base dati originale; +- può essere creata da uno snapshot; +- può essere analizzata con il modulo manager; +- può essere modifica nel modulo editor. diff --git a/pages/appendici/appendix-gtfs-warnings.md b/pages/appendici/appendix-gtfs-warnings.md new file mode 100644 index 0000000..f989908 --- /dev/null +++ b/pages/appendici/appendix-gtfs-warnings.md @@ -0,0 +1,133 @@ +--- +title: Glossario degli errori +parent: Appendici +nav_order: 1 +--- + +# 1- Errori di validazione + +Gli errori sono consultabili dagli utenti nella sezione dedicata nel manager. La correzione delle segnalazioni non può avvenire nel manager ma solo in fase di modifica del feed. + +![img](/img/overview-data-validation.png) + +Di seguito sono riportati alcuni degli errori più comuni: + +##### Corse spurie nel percorso +Alcuni percorsi risultano avere al loro interno delle corse con km contrattuali diversi da quelli riportati nel percorso. Valutare se spostare tali corse in nuovi percorsi. + +*Questo errore deve necessariamente essere corretto ai fini di una corretta gestione del feed.* + +##### Codici corsa duplicati a livello di linea +Alcune linee risultano avere corse con codice corsa duplicato. È necessario che il codice corsa sia univoco all'interno di una linea. + +*Questo errore deve necessariamente essere corretto ai fini di una corretta gestione del feed.* + +##### Codici corsa duplicati a livello di percorso +Alcuni percorsi risultano avere corse con codice corsa duplicato. È necessario che il codice corsa sia univoco all'interno di un percorso della linea. + +*Questo errore deve necessariamente essere corretto ai fini di una corretta gestione del feed.* + +##### Calendari duplicati +Alcuni calendari risultano avere la stessa definizione di giorni di servizio. Sarebbe opportuno evitare la proliferazione dei calendari. + +*È consigliabile evitare di creare calendari uguali tra loro. All'appendice 3 - Nomenclatura calendari si possono trovare maggiori informazioni sull'argomento* + +##### Tempo di viaggio nullo +Il veicolo arriva alla fermata allo stesso orario in cui parte dalla precedente. + +*Questo errore può essere trascurato in caso di fermate molto vicine, in cui varia solo la cifra relativa ai secondi.* + +##### Tempo di viaggio negativo +Il veicolo arriva a questa fermata prima di partire dalla precedente. + +*È consigliabile controllare la correttezza degli intertempi e degli orari di partenza e sosta in una fermata.* + +##### Data senza servizio +Non vi sono service_id attivi per una data compresa nell'intervallo di date con un servizio definito. + +*Questo errore può essere trascurato in caso vi siano giorni in cui non è attivo il servizio di trasporto.* + +##### Fermata in area a bassa densità abitativa +Una fermata è posizionata in un'area geografica con una bassa densità di popolazione. + +*Questo errore può essere trascurato in caso il posizionamento della fermata sia corretto.* + +##### Tragitto troppo lento +Il veicolo sta viaggiando molto lentamente per raggiungere la fermata rispetto a quella precedente. + +*Questo segnalazione è sintomo di una errata velocità commerciale rispetto a quanto ammissibile per il tipo di strada. È consigliabile controllare gli intertempi tra le fermate.* + +##### Tragitto troppo rapido +Il veicolo sta viaggiando molto velocemente per raggiungere la fermata rispetto a quella precedente. + +*Questo segnalazione è sintomo di una errata velocità commerciale rispetto a quanto ammissibile per il tipo di strada. È consigliabile controllare gli intertempi tra le fermate.* + +##### Fermata non utilizzata +La fermata non è utilizzata da alcuna corsa. + +*Questo errore è presente in ogni feed di Transit Café, in quanto sono presenti tutte le fermate regionali all'interno di ogni feed.* + +##### Il nome breve della linea e il nome esteso sono vuoti +Una linea non ha il nome breve della linea o il nome esteso. + +*Sia il nome breve che il nome esteso sono richiesti dalle specifiche GTFS.* + +##### Il nome breve di una linea è troppo lungo +Il campo nome breve di una linea ha troppi caratteri. + +*Il nome breve di una linea non dovrebbe contenere più di 3-4 caratteri, dato che le applicazioni che usano il GTFS potrebbero usare il nome breve in contesti in cui vi sono limiti di spazio per il testo (es. etichette su una mappa).* + +##### Il nome esteso della linea contiene il nome breve +Lo nome breve di una linea è incluso nel nome esteso. + +*Il nome esteso della linea non deve contenere il nome breve, dato che le applicazioni che usano il GTFS potrebbero combinare il nome esteso e quello breve per un nome combinato (es. una linea con nome breve “A” e nome esteso “Dora Express” può essere indicata come “A - Dora Express”).* + +##### La descrizione della linea è uguale al nome della linea +La descrizione e il nome di una linea sono identici. + +*La descrizione è un campo opzionale e dovrebbe essere incluso solo se fornisce informazioni aggiuntive oltre a ciò che è incluso nel nome della linea.* + +##### Tipo mezzo che opera la linea non valido +Un tipo mezzo specificato non corrisponde a nessuno dei valori di tipo mezzo definiti da GTFS. + +*I valori accettati per il campo in analisi sono definiti nelle specifiche del GTFS e attualmente includono 8 differenti modalità di trasporto (tram, metropolitana, treno, bus, traghetto, funivia, funicolare).* + +##### Nessun orario per la corsa +Una corsa non contiene informazioni sui passaggi in fermata. + +*Questo indica che le informazioni sugli orari per questa corsa non sono corrette.* + +##### Orario partenza prima dell'arrivo +Una corsa inizia una fermata prima del suo termine. + +*Questo indica che le informazioni sugli orari per questa corsa non sono corrette.* + +##### Passaggio in fermata non in sequenza +Una corsa arriva prima di partire dalla fermata precedente. + +*Questo indica che le informazioni sugli orari per questa corsa non sono corrette.* + +##### Corsa duplicata +Due o più corse condividono la stessa sequenza di fermate e orari di partenza. + +*Questo indica che ci possono essere corse duplicate.* + +##### Corse sovrapposte nel block +Due o più corse con sovrapposizione di un block. + +*Un block rappresenta una sequenza di corse operate da un singolo veicolo, e il block ID è un campo opzionale che indica a blocco appartiene il veicolo. Se la numerazione del block è usata nella registrazione della corsa, e due o più corse si sovrappongono nel tempo ma condividono un comune block ID, allora questo indica o la presenza di informazioni sbagliate sugli orari programmati o block ID non corretto .* + +##### Fermate duplicate +Due fermate hanno la stessa posizione in un feed. + +*Considera di unire le fermate che condividono la stessa posizione o usa la gerarchia stazione/fermata per specificare le posizioni di un gruppo di fermate.* + +##### Tracciato geometrico della corsa al contrario +La direzione del tracciato geometrico della corsa non corrisponde a quella della sequenza di fermate. + +*Invertire o correggere lo shape della corsa in modo da adattarsi all'ordine delle fermate di questa corsa.* + +##### Geometria mancante +La corsa non ha un tracciato geometrico di riferimento. + +*Gli shape sono opzionali ma raccomandati.* diff --git a/pages/appendici/appendix-naming-calendar.md b/pages/appendici/appendix-naming-calendar.md new file mode 100644 index 0000000..27019f8 --- /dev/null +++ b/pages/appendici/appendix-naming-calendar.md @@ -0,0 +1,61 @@ +--- +title: Nomenclatura calendari +parent: Appendici +nav_order: 1 +--- + +# 3 - Nomenclatura calendari + +Di seguito sono riportate alcune sigle utili per identificare un calendario. L'elenco riprende la nomenclatura adottata dal sistema Omnibus a livello regionale: + +| Id calendario | Descrizione | +|---------------|-----------------------------------------------------------------------| +| 1 | Lunedì | +| 2 | Martedì | +| 3 | Mercoledì | +| 4 | Giovedì | +| 5 | Venerdì | +| PREF | Giorni prefestivi | +| SAB | Sabato | +| DOM | Domenica | +| SAB+PF | Sabato e prefestivi | +| E | Periodo estivo | +| I | Periodo invernale | +| A | Solo agosto | +| -A | Escluso agosto | +| -H | Escluso 2 settimane ad agosto | +| -F | Escluso 3 settimane ad agosto | +| -A4 | Escluso 4 settimane ad agosto | +| -S | Periodo non scolastico | +| FER2 | Feriale 2 gg. settimana | +| FER3 | Feriale 3 gg. settimana | +| FER4 | Feriale 4 gg. settimana | +| FER5 | Feriale escluso sabato | +| FER6 | Feriale compreso sabato | +| FER5-FN | Feriale escluso sabato escluso settimana di Ferragosto e Natale | +| GIOR | Giornaliera (feriali e festivi) | +| FER-SLV | Feriale esclusi giorni scolatici dal lunedì al venerdì | +| FEST | Festiva | +| FEST/B | Festiva dal 01/04 al 30/09 | +| FEST/B2 | Festiva dal 01/01 al 31/03 e dal 01/10 al 31/12 | +| FEST-3 | Festiva escluso Natale, Capodanno e 1° maggio | +| FEST-7 | Solo giorni festivi | +| FEST-N | Festiva escluso Natale | +| FEST-NC | Festiva escluso Natale e Capodanno | +| NAT | Solo giorno di Natale | +| SABFESTLA | Sabato e giorni festivi domenica compresa nei mesi di luglio e agosto | +| SCOL | Scolastica | +| SCOLG2 | Scolastica 2 gg. settimana | +| SCOLG3 | Scolastica 3 gg. settimana | +| SCOLG4 | Scolastica 4 gg. settimana | +| SCOLG5 | Scolastica 5 gg. settimana | + +Le singole sigle possono essere combinate per dare origine a particolari calendari, ad esempio: + +| Id calendario | Descrizione | +|---------------|-----------------------------------------------------------------------------------| +| FER5GGI | Feriale 5 gg. settimana periodo invernale | +| SCOL1 | Scolastica lunedì | +| FER5-A/B | Feriale escluso sabato e agosto a settimane alterne | +| FER5-A/C | Feriale escluso sabato e agosto a settimane alterne | +| FER6-SA/B2 | Feriale compreso sabato periodo non scolatico escluse 2° e 3° settimana di agosto | diff --git a/pages/appendici/appendix-video-tutorial.md b/pages/appendici/appendix-video-tutorial.md new file mode 100644 index 0000000..cd8304f --- /dev/null +++ b/pages/appendici/appendix-video-tutorial.md @@ -0,0 +1,54 @@ +--- +title: Video tutorial +parent: Appendici +nav_order: 1 +--- + +# 4 - Video tutorial + +Di seguito sono riportati i video tutorial realizzati per illustrare l'utilizzo di Transit Café. I video sono anche disponibili nelle relative sezioni tematiche della guida all'uso. + +###### 1 - Creazione Linea +Il video illustra il procedimento da seguire per la creazione di una nuova linea in un feed: + +[![Creazione Linea](/img/video-creazione-linea.png)](http://www.youtube.com/watch?v=gU6mL0u_gik "Tutorial Café 1 - Creazione Linea") + +###### 2 - Creazione Percorso +Il video illustra il procedimento da seguire per la creazione di un nuovo percorso di una linea: + +[![Creazione Percorso](/img/video-creazione-percorso.png)](http://www.youtube.com/watch?v=mzma-U-ZVAE "Tutorial Café 2 - Creazione Percorso") + +###### 3 - Modifica Geometria Percorso +Il video illustra il procedimento da seguire per la modifica della geometria del percorso di una linea: + +[![Modifica Geometria Percorso](/img/video-modifica-percorso.png)](http://www.youtube.com/watch?v=9_gbgRUAuXI "Tutorial Café 3 - Modifica Geometria Percorso") + +###### 4 - Versionamento Percorso +Il video illustra il procedimento da seguire per versionare il percorso di una linea: + +[![Versionamento Percorso](/img/video-versionamento-percorso.png)](http://www.youtube.com/watch?v=mFTtU61u7rs "Tutorial Café 4 - Versionamento Percorso") + +###### 5 - Creazione Nuovo Calendario +Il video illustra il procedimento da seguire per la creazione di un nuovo calendario: + +[![Creazione Calendario](/img/video-creazione-calendario.png)](http://www.youtube.com/watch?v=FIsItzlJzek "Tutorial Café 5 - Creazione Calendario") + +###### 6 - Inserimento Corse +Il video illustra il procedimento da seguire per l'inserimento di nuove corse in un calendario: + +[![Inserimento Corsa](/img/video-inserimento-corsa.png)](http://www.youtube.com/watch?v=fWzEeUzw0PE "Tutorial Café 6 - Inserimento Corsa") + +###### 7 - Gestione Corse +Il video illustra il procedimento da seguire per la modifica delle corse presenti in un calendario: + +[![Gestione Corse](/img/video-gestione-corse.png)](http://www.youtube.com/watch?v=IJ9n-wK-YhE "Tutorial Café 7 - Gestione Corse") + +###### 8 - Snapshot e Versioni +Il video illustra il procedimento da seguire per la creazione di uno snapshot e la seguente promozione a versione: + +[![Snapshot e Versioni](/img/video-snapshot-versioni.png)](http://www.youtube.com/watch?v=RTKJdkwbokk "Tutorial Café 8 - Snapshot e Versioni") + +###### 9 - Aggiunta e rimozione fermate dai percorsi +Il video illustra il procedimento da seguire per aggiungere/rimuovere una fermata dal percorso e aggiornare automaticamente gli orari delle corse: + +[![Aggiunta e rimozione fermate dai percorsi](/img/video-aggiunta-rimozione-fermate-percorso.png)](http://www.youtube.com/watch?v=lI7H8DlH1cE "Tutorial Café 9 - Aggiunta e rimozione fermate dai percorsi") diff --git a/pages/appendici/index.md b/pages/appendici/index.md new file mode 100644 index 0000000..2f8d769 --- /dev/null +++ b/pages/appendici/index.md @@ -0,0 +1,7 @@ +--- +title: Appendici +nav_order: 6 +--- + +# Appendici + diff --git a/pages/editor/agencies.md b/pages/editor/agencies.md new file mode 100644 index 0000000..75fe383 --- /dev/null +++ b/pages/editor/agencies.md @@ -0,0 +1,40 @@ +--- +title: Aziende +parent: Editor +nav_order: 2 +--- + +# Aziende + +In questa pagina si possono trovare le informazioni inerenti gli operatori/aziende di trasporto pubblico che operano il servizio. + +## Inserimento di una nuova azienda + +Per creare una nuova azienda di trasporto, clicca `+ Aggiungi azienda`. +Per inserire i dettagli di una nuova azienda, o operatore di trasporto, è necessario compilare alcuni campi obbligatori richiesti dalle specifiche GTFS: + +- *Nome dell'azienda*: il nome completo dell'azienda o operatore del servizio; +- *Sito web dell'azienda*: la url del sito web dell'azienda, deve contenere http:// o https://; +- *Fuso orario dell'azienda*: il fuso orario di riferimento in base alla posizione geografica dell'azienda. + +![screenshot](/img/agency-mandatory-fields.png) + +I campi obbligatori sono evidenziati in rosso dal sistema fino al termine della loro compilazione; la mancanza di uno di questi campi non permette il salvataggio delle informazioni. +Ad ogni azienda, se non completato in fase di inserimento dati, sarà assegnato un id azienda univoco. + +Sono inoltre disponibili alcuni campi opzionali: + +- *Id dell'azienda*: identificativo univoco di una azienda di trasporto; +- *Numero di telefono*: numero di telefono di contatto dell'azienda; +- *Url della pagina delle tariffe*: la URL di una pagina web che permette di acquistare biglietti online, deve contenere http:// o https://; +- *Email dell'azienda*: indirizzo email di contatto dell'azienda; +- *Url del logo dell'azienda*: URL in cui è possibile specificare il logo dell'azienda; +- *agency branding asset*: campo in cui è possibile inserire tramite drag&drop/trascinare il logo dell'azienda di trasporto. + +**Nota:** come per i nuovi oggetti creati (ad eccezione dei percorsi), la nuova azienda non sarà salvata finchè non sarà cliccato il tasto salva (💾). + +## Modifica azienda + +Per iniziare a modificare le informazioni relative alle aziende esercenti il servizio, clicca il marker corrispondente nella barra di navigazione a sinistra. + +![screenshot](../../img/agency-detail.png) diff --git a/pages/editor/calendars.md b/pages/editor/calendars.md new file mode 100644 index 0000000..a39b60d --- /dev/null +++ b/pages/editor/calendars.md @@ -0,0 +1,50 @@ +--- +title: Calendari +parent: Editor +nav_order: 5 +--- + +# Calendari +Da questa sezione è possbile impostare il periodo di validità delle corse. + +#### Modifica o crea calendari + +Per iniziare a modificare i calendari, clicca l'icona 📅 nella barra di navigazione a sinistra e scegli un calendario dalla lista. + +![screenshot](../../img/edit-calendars.png) + +Per creare un nuovo calendario, clicca `+ Aggiungi calendario`. + +Il campo *Id calendario* può essere compilato a piacere; per avere qualche indicazione sulla nomenclatura esistente si può consultare la pagina [Nomenclatura calendari](../appendix-naming-calendar). + +*Nota*: come per i nuovi oggetti creati (ad eccezione dei percorsi), il nuovo calendario non sarà salvato fino alla selezione del tasto `Salva`(💾). + +#### Dettagli del calendario +È necessario compilare alcuni campi come da specifiche GTFS: + +- *Id calendario*: identificativo univoco per il calendario; +- *Descrizione*: descrizione opzionale per il calendario (default impostato sui giorni della settimana specificati); +- *Giorni in cui è attivo il servizio*: giorni della settimana in cui opera il servizio; +- *Data di inizio validità* e *Data di termine validità*: il primo e ultimo giorno di validità assegnato ad un calendario. + +È inoltre presente il numero dei giorni di servizio che varia dinamicamente a secondo delle modifiche dell'utente al calendario di validità del servizio. + +Il calendario sottostante riporta per esteso i giorni di attività del servizio formattati secondo la simbologia in vigore. + +![screenshot](../../img/calendar-detail.png) + +Sopra il campo `Descrizione` è presente un punto interrogativo: cliccandovi sarà possibile consultare la legenda. + +![zoom](../../img/calendar-legend.png) + +Per maggiori dettagli sulla creazione di un calendario, è possibile consultare il seguente *video tutorial*: + +[![Creazione Calendario](../img/video-creazione-calendario.png)](http://www.youtube.com/watch?v=FIsItzlJzek "Tutorial Café 5 - Creazione Calendario") + + +#### Modifica orari corse +Clicca `Vai all'editor corse` per iniziare a creare o modificare i passaggi in fermata programmati per un percorso di una linea. Sarai reindirizzato all'*editor corse*. + +*Nota*: devono essere stati creati in precedenza almeno una linea, un percorso e un calendario per poterne modificare gli orari. + +Per ulteriori informazioni su come associare gli orari ad un percorso, vedi [Orari](schedules). diff --git a/pages/editor/fares.md b/pages/editor/fares.md new file mode 100644 index 0000000..a2ae155 --- /dev/null +++ b/pages/editor/fares.md @@ -0,0 +1,41 @@ +--- +title: Tariffe +parent: Editor +nav_order: 7 +--- + +# Tariffe + +## Modifica tariffe + +Per iniziare a modificare le tariffe dei biglietti, clicca l'icona del biglietto nella barra di navigazione a sinistra. + +![screenshot](../../img/edit-fares.png) + +Scegli una tariffa dalla lista per iniziare le modifiche. Per creare una nuova tariffa, clicca `+ Nuova tariffa`. **Nota:** come le tutte le nuove entità create (ad eccezione dei percorsi), la nuova tariffa non sarà salvata finchè non sarà selezionata l'icona del salvataggio (💾). + +## Attributi della tariffa + +Gli attributi della tariffa descrivono le informazioni di base di una tariffa. Ulteriori dettagli in merito sono disponibili sulle [specifiche GTFS](https://developers.google.com/transit/gtfs/reference/fare_attributes-file). + +## Regole tariffarie + +Per modificare le regole che definiscono le tariffe, è necessario creare e salvare una tariffa con attributi. Dopo aver scelto una tariffa, clicca il tab `Regole tariffa` e definisci una o più regole utilizzando le tipologie seguenti: + +1. **Linea** - si applica ad ogni itinerario che include una linea +2. **Dalla/alla zona** - si applica ad ogni itinerario che è percorso dalla zona di origine a quella di destinazione +3. **Contiene zona** - si applica ad ogni itinerario che attraversa *ogni* zona `contenuta` + +**Nota:** le regole delle tariffe possono essere complesse, vedi le [specifiche GTFS](https://developers.google.com/transit/gtfs/reference/fare_rules-file) per ulteriori informazioni sull'applicazione delle regole tariffarie. +
+ ![screenshot](../../img/edit-fare-rules.png) +
+ +## Crea zone tariffarie + +Per creare una zona tariffaria da utilizzare nelle regole di tariffazione, è prima necessario selezionare una fermata che si vuole includere nella zona. Clicca nel menu a discesa `zone_id` ed inizia a digitare il nuovo `zone_id`. Clicca `Crea nuova zona: [zone_id]` e poi salva la fermata. Ripeti l'operazione per tutte le zone di cui si ha bisogno. +
+ ![screenshot](../../img/add-fare-zone.png) +
+ +Una volta create ed assegnate ad una o più fermate, le zone tariffarie possono essere utilizzate nella definizione delle regole tariffarie per **Dalla/alla zona** o **Contiene zona**. diff --git a/pages/editor/feed_info.md b/pages/editor/feed_info.md new file mode 100644 index 0000000..761199b --- /dev/null +++ b/pages/editor/feed_info.md @@ -0,0 +1,27 @@ +--- +title: Feed info +parent: Editor +nav_order: 1 +--- + +# Feed info + +Questa pagina contiene informazioni generiche sulla base dati in analisi. È richiesta la compilazione di alcuni campi obbligatori: + +- *Nome contratto annuale*: il nome dell'azienda/ente che pubblica il feed; +- *Sito web dell'ente che pubblica il dato*: la url dell'ente/azienda che pubblica il feed; + +Sono inoltre presenti i seguenti campi opzionali: + +- *Data di inizio validità del feed*: la data di inizio validità del servizio programmato descritto nel feed; +- *Data di fine validità del feed*: la data di fine validità del servizio programmato descritto nel feed; +- *Colore di default*: colore da associare al feed; +- *Tipo mezzo di default*: tipo mezzo di default che opera il servizio (esempio bus, treno, metro, ecc.); +- *Id feed*: identificativo del feed; +- *Id ente*: identificativo dell'ente di riferimento per il servizio; +- *Codice del contratto*: codice del contratto di servizio registrato presso l'Osservatorio del Ministero dei Trasporti. + +Il campo **Nome contratto annuale** è utilizzato nell'intestazione dei report in formato pdf presenti nella parte manager. In caso questo campo non sia compilato, il titolo del report non sarà completo sui pdf. + + +![screenshot](../../img/feed-info.png) diff --git a/pages/editor/index.md b/pages/editor/index.md new file mode 100644 index 0000000..1d02ce0 --- /dev/null +++ b/pages/editor/index.md @@ -0,0 +1,45 @@ +--- +title: Editor +nav_order: 4 +--- + +# Concetti generali + + +L'**Editor** di Transit Café permette agli utenti di modificare i file GTFS e i PEA importati dal manager (vedi [Caricare versioni di feed nell'editor](../../user/managing-projects-feeds/#loading-feed-versions-into-editor)) o di creare un GTFS o un PEA da zero. + +Una volta iniziata la modifica di un feed, è possibile effettuare alcune operazioni descritte di seguito. + +##### Salvare nell'Editor + +Quando si modificano elementi nell'Editor, è necessario salvare manualmente ogni cambiamento usando il tasto con l'icona del salvataggio (💾) per evitare modifiche accidentali. L'unica eccezione è per i percorsi, le cui modifiche vengono salvate automaticamente. + +##### Navigare nell'Editor + +Le principali componenti di un file GTFS (feed info, routes, stops e calendars) corrispondono alle icone presenti nella barra di navigazione sulla sinistra dello schermo. Cliccando su queste icone, è possibile creare, modificare o cancellare elementi nel feed. + +Dalla pagine delle **[Linee](routes)** si può accedere alle sottosezioni relative a: + +- **[Percorsi](patterns)** (entità *shapes* e *stop times* del GTFS): permettono agli utenti di creare una o più sequenze di fermate per una data linea. Per esempio, una linea potrebbe avere un percorso inbound (da periferia a centro) e outbound (da centro a periferia). +- **[Orari](schedules)** (entità *trips* e *frequencies* del GTFS): definisce le corse di un percorso, che saranno definite in base agli orari di passaggio in fermata o intervalli di frequenza. + +##### Utilizzare la barra di accesso rapido + +Nell'angolo in basso a destra dell'Editor, è posizionata la barra di accesso rapido che ha alcune funzionalità utili in fase di modifica. + +![quick access toolbar](../../img/quick-access-toolbar.png) + +Da sinistra a destra, queste funzionalità sono: + +- nascondi la barra di accesso rapido; +- tasto multifunzione con il nome del feed che permette di: + - tornare al feed; + - tornare al progetto; + - vedere il nome della versione di origine dei dati in modifica nell'editor + - riferimento al database che contiene i dati della versione in modifica nell'editor. + + ![quick access toolbar](../../img/quick-access-toolbar-feed-source.png) + +- carica uno shapefile dei percorsi delle linee per visualizzare le polilinee come aiuto visivo per la digitalizzazione dei percorsi. Il file dovrà essere caricato in formato *.zip*; +- crea un nuovo elemento (azienda, fermata, linea, calendario, ecc.); +- fai uno snapshot (punto di salvataggio) per lo stato corrente del dato (o torna allo snapshot precedente). diff --git a/pages/editor/line_snapshot.md b/pages/editor/line_snapshot.md new file mode 100644 index 0000000..8f510dd --- /dev/null +++ b/pages/editor/line_snapshot.md @@ -0,0 +1,29 @@ +--- +title: Snapshot della linea +parent: Linee +--- + +# Snapshot della linea + +Questa funzionailtà permette di isolare una linea in un ambiente di lavoro e poterla reimportare in un feed esistente. + +Il flusso di lavoro da seguire è: + +- dalla scheda *Dettagli linea* nell'editor si seleziona il tasto `Fai uno snapshot della linea`; + +![zoom](../../img/snapshot-line.png) + +- lo snapshot della linea contiene solo la linea in questione e può essere caricato sull'editor per apportare le modifiche necessarie, eseguendo opportuni snapshot durante le fasi di lavoro; +- parallelamente il feed originale può subire modifiche ed essere versionato più volte; +- ultimate le variazioni sulla linea, si promuove a versione lo snapshot finale della linea per procedere all'unione della linea modificata con il feed completo; +- dal manager si seleziona la versione contenente la sola linea e tramite il menu a tendina `Unisci alla versione` si sceglie la versione del feed completo su cui si vuole riversare la linea; +- questa operazione origina un nuovo snapshot che prende il nome nella forma *nome Feed completo + nome Linea modificata*; +- lo snapshot può essere caricato nell'editor per verifica/ulteriori modifiche ed infine promosso a versione definitiva e completa. + +![screenshot](../../img/version-union.png) + +Alcuni dettagli relativi alla logica di unione a cui fare attenzione: + +- la linea isolata e poi riunita sovrascrive completamente la sua copia nel feed di origine, compresa di percorsi, corse e geometrie dei percorsi; +- se sulla versione della linea separata si crea un nuovo calendario, a cui si associano corse della linea, questo viene importato come nuovo calendario sul feed di unione; +- se si modificano calendari esistenti, le modifiche **non** vengono riportate sul feed di unione, dove gli stessi calendari potrebbero aver subito variazioni durante il normale flusso di lavoro. diff --git a/pages/editor/patterns.md b/pages/editor/patterns.md new file mode 100644 index 0000000..36101ab --- /dev/null +++ b/pages/editor/patterns.md @@ -0,0 +1,181 @@ +--- +title: Percorsi +parent: Linee +--- + +# Percorsi + +In questa pagina si possono trovare le informazioni inerenti la descrizione dei percorsi presenti nel territorio in cui è attivo il servizio. + +## Modifica o crea percorsi + +Per iniziare a modificare percorsi, è necessario selezionare o creare una linea. Clicca sul tab `Percorsi`. + +![screenshot](../../img/edit-patterns.png) + +Dopo aver selezionato un percorso tra quelli proposti, puoi utilizzare il tasto `Zoom all'estensione del percorso` rappresentato con l'icona 🔍 (in alto nella barra degli strumenti) e sulla mappa sarà visualizzato l'intero percorso che si sta modificando. + +Per creare un nuovo percorso , clicca `+ Nuovo percorso`. + +### Barra degli strumenti percorso + +- **Versiona percorso**: permette di duplicare un percorso e tutte le corse ad esso associate. Viene richiesta una data di inizio validità del nuovo percorso ed automaticamente viene limitata la validità del percorso di partenza. + +- **Termina percorso**: permette di terminare un percorso e tutte le corse ad esso associate. Viene richiesta una data di termine validità da applicare alle corse. + +- **Inverti percorso**: per invertire la sequenza di fermate di un percorso, clicca il tasto con le frecce opposte. + + *Nota*: questa è una azione distruttiva e dovrebbe essere utilizzata solo per un percorso duplicato. + +- **Duplica percorso**: crea una copia del percorso attivo (il nome del percorso duplicato diventerà `[Nome percorso] copy`) se è necessario crearne uno similare, ma con una geometria differente. + +- **Elimina percorso**: elimina il percorso attivo. + + *Nota*: i percorsi cancellati non potranno essere ripristinati. + +![patternToolbar](../../img/pattern-toolbar.png) + +## Dettagli percorso + +Per ogni percorso sono definite le seguenti informazioni: + +- *Nome*: il nome del percorso della linea, ad esempio un servizio che percorre l'intera lunghezza della linea o che ne copre solo una parte. +- *Lunghezza su mappa*: indica la lunghezza in metri del percorso misurato su cartografia. +- *Lunghezza contrattuale*: indica la lunghezza in metri ufficialmente assegnata al percorso, sulla quale vengono poi calcolati i corrispettivi contrattuali. Questo campo è modificabile cliccando sulla matita presente vicino al numero. +- *Tipo corsa*: indica se la corsa è di tipo *Urbano* o *Extraurbano*. +- *Shape_id*: identificativo della geometria. +- *Modifica geometria percorso*: cliccando su questo tasto sarà possibile modificare la geometria del tracciato. Per maggiori dettagli consulta le sezioni seguenti della documentazione. +- *Da fermate*: questo tasto permette di creare una nuova geometria per il percorso in esame a partire dalle fermate ad esso associate. + + *Non sarà possibile tornare alla geometria iniziale utilizzando questo comando.* + +*Nota*: questa operazione sovrascrive il precedente tracciato, che rimarrà visibile con un tratteggio rosso nella sessione di modifica corrente ma non sarà selezionabile dall'utente. + +- *Usa orari/frequenze*: indica se il percorso usa gli orari o le frequenze di passaggio in fermata. +- *Direzione*: corrisponde al campo `direction_id` del GTFS. Tutte le corse associate al percorso avranno associata la direzione indicata: questo dato può essere valorizzato come `outbound` (movimento dal centro città verso fuori), `inbound` (movimento da fuori città verso il centro) oppure può essere nullo. + +![img](../../img/shape-shadow.png) + +#### Barra degli strumenti per le fermate nella linea +La barra degli strumenti per le fermate è raggiungibile cliccando la fermata del percorso su mappa ed è una scorciatoia per alcuni comandi: + +- *Salva*: salva ogni modifica al tempo di viaggio e di attesa. +- *Rimuovi*: rimuovi la fermata dal percorso. +- *Aggiungi*: aggiungi la fermata alla sequenza. Questo è utile per percorsi che potrebbero utilizzare la stessa fermata più volte (es. linee circolari). + +![zoom](../../img/pattern-stop-toolbar.png) + +## Sequenza fermate +#### Aggiungi fermata +Un percorso contiene una sequenza di fermate: per inserirle clicca `+ Aggiungi fermata`. È possibile aggiungere fermate cercandole per nome dal menu a discesa che appare o facendo zoom sulla mappa e cliccando sull'icona della fermata e selezionando `+ Aggiungi fermata`. + +![zoom](../../img/pattern-add-stop.png) + +Aggiungendo fermate, il tracciato del percorso sarà aggiornato seguendo la rete stradale fino al completamento della linea. + +Per maggiori dettagli sulla creazione di un percorso a partire da una sequenza di fermate, è possibile consultare il seguente *video tutorial*: + +[![Creazione Percorso](../../img/video-creazione-percorso.png)](http://www.youtube.com/watch?v=mzma-U-ZVAE "Tutorial Café 2 - Creazione Percorso") + +#### Inserisci fermate all'interno della sequenza delle fermate +Se ti accorgi di aver saltato una fermata della sequenza, la potrai aggiungere in seguito senza alcuna complicazione. Se aggiungi fermate dal menu a discesa, queste possono essere inserite solo alla fine della sequenza. Nel caso di inserimento da mappa, si potrà scegliere l'ordine in cui inserire la nuova fermata. + +![screenshot](../../img/pattern-insert-stop.png) + +#### Cambiare l'ordine delle fermate +Se una fermata si trova nell'ordine sbagliato all'interno della sequenza, è possibile selezionarla e trascinarla nella posizione corretta dalla visualizzazione come lista. L'ordine della sequenza di fermate sarà aggiornato solo al termine del trascinamento della casella. + +*Nota*: inserendo fermata all'interno della sequenza o cambiando l'ordine delle fermate, il tracciato del percorso non sarà aggiornato automaticamente. Sarà necessario modificare il tracciato manualmente o cliccare sul tasto `Crea` per rigenerare la geometria del tracciato del percorso a partire dalle fermate. + +![zoom](../../img/pattern-stop-order.png) + +#### Rimozione fermate +Le fermate possono essere rimosse dal percorso cliccando sul tasto rosso 🗑 nella scheda estesa della fermata o cliccando sulla fermata di interesse dalla mappa. + +![zoom](../../img/pattern-stop-remove.png) + +#### Modifica orari corse +Clicca `Vai all'editor corse` per iniziare a creare o modificare corse/frequenze per un percorso: sarai reindirizzato all'Editor corse. Per ulteriori informazioni sulla creazione di orari per un percorso, vedi [Orari](schedules). + +#### Aggiorna orari corse +Lo strumento `Aggiorna orari corse` permette di aggiornare automaticamente tutti gli orari di tutte le corse di un percorso quando, ad esempio, si aggiungono o rimuovono fermate dal percorso. Cliccando `Aggiorna orari corse` si sovrascrivono gli orari di arrivo e partenza per tutte le corse del percorso in analisi, in modo da rispettare i tempi di viaggio e di sosta impostati a livello di percorso. +È inoltre possibile aggiornare gli orari solo a partire da una determinata fermata scelta dall'utente: in questo caso le modifiche saranno applicate esclusivamente a partire dalla fermata selezionata. + +![screenshot](../../img/normalize-stop-time.png) + +*Nota*: questa operazione sovrascriverà anche gli orari modificati a mano sull'editor corse. + +Per maggiori dettagli sull'aggiunta/rimozione di una fermata dal percorso e il conseguente aggiornamento degli orari delle corse, è possibile consultare il seguente *video tutorial*: + +[![Aggiunta e rimozione fermate dai percorsi](../../img/video-aggiunta-rimozione-fermate-percorso.png)](http://www.youtube.com/watch?v=lI7H8DlH1cE "Tutorial Café 9 - Aggiunta e rimozione fermate dai percorsi") + +## Passaggi in fermata +#### Calcola passaggi +La velocità media della linea può essere utilizzata per calcolare gli intertempi tra fermate. Una volta aggiunte le fermate e creato il tracciato, è sufficiente cliccare `Calc. Tempi` e gli intertempi tra fermate saranno compilati automaticamente. Si possono inserire informazioni legate a: + +- *Velocità media*: la velocità media (in km/h) da usare per calcolare i tempi; +- *Tempo di sosta*: permette di assegnare lo stesso tempo di sosta alle fermate di una linea. + +#### Tempi inseriti manualmente +I tempi per ogni fermata possono essere assegnati sia dalla scheda della fermata nella lista delle fermate sia cliccando sulla fermata dalla mappa. È necessario compilare 2 campi: + +- *Tempo di viaggio*: tempo impiegato per arrivare alla fermata corrente da quella precedente (dovrebbe essere pari a 00:00 nella prima fermata della sequenza); +- *Tempo di sosta*: tempo in cui il veicolo resta in attesa in fermata prima di partire per la fermata successiva. + +## Modifica geometria percorso +Come menzionato in precedenza, il tracciato della linea sarà disegnato automaticamente in base a come vengono inserite le singole fermate all'interno della sequenza. Tuttavia, se fosse necessario migliorare il tracciato generato automaticamente, cliccando su `Modifica geometria percorso` sarà possibile modificare i segmenti del tracciato che compongono il percorso. +Selezionando un arco del percorso, questo sarà evidenziato in verde ad indicare che il tratto selezionato è attivo e modificabile. + +![screenshot](../../img/edit-pattern-geometry.png) + +Gli estremi del tratto selezionato saranno evidenziati con un quadrato di colore *blu* (primo nodo del tratto) e *rosso* (nodo finale). Il nodo selezionato sarà indicato con un *quadrato nero*, se coincidente con un fermata, oppure con una *x nera*, in caso rappresenti un punto di ancoraggio. Sono inoltre presenti i tasti `Prec` e `Suc` con relativa icona per scorrere rapidamente tra i vertici dei singoli tratti del tracciato. + +*Nota*: per una visualizzazione ottimale in fase di modifica, si consiglia di disabilitare `Nascondi punti di ancoraggio delle fermate` e `Mostra fermate`. + +Per maggiori dettagli sulla modifica della geometria di un percorso, è possibile consultare il seguente *video tutorial*: + +[![Modifica Geometria Percorso](../../img/video-modifica-percorso.png)](http://www.youtube.com/watch?v=9_gbgRUAuXI "Tutorial Café 3 - Modifica Geometria Percorso") + +#### Caricamento geometria esistente per ricalco + +In caso si volesse tracciare la geometria a partire da uno shapefile esistente, è possibile selezionare nella barra di accesso rapido in basso a destra il tasto centrale con l'icona di una freccia verso l'alto ⬆️. + +![zoom](../../img/upload-shp.png) + +Si aprirà quindi una finestra che permette di caricare uno shapefile zippato contenente la geometria di interesse. Questi tracciati saranno visualizzati su mappa come sfondo e potranno essere ricalcati utilizzando gli strumenti di modifica percorso di Transit Café. + +![screenshot](../../img/upload-zip-shp.png) + +Ogni geometria presente nello shapefile è cliccabile e mostra tutte le informazioni presenti nella tabella attributi. + +![screenshot](../../img/pattern-popup.png) + +Le geometrie degli shapefile sono rappresentate con colori assegnati in modalità casuale, che cambia con ogni operazione di pan/zoom su mappa. Se nella tabella attributi dello shapefile fosse presente un campo denominato "COLOR" contenente il colore in formato esadecimale (ad esempio *#336688*), questo sarà assegnato alla geometria di riferimento. + +#### Modifiche di base + +Una volta modificato il tracciato di una linea, ci sono alcune funzionalità a cui prestare attenzione: + +- trascinando un nodo (✕) sarà creato un nuovo allineamento tra fermate o con i nodi circostanti; +- cliccando due volte sull'arco attivo del tracciato, sarà aggiunto un nodo al segmento. + +Sono inoltre disponibili le seguenti opzioni abilitabili in fase di modifica: + +- *Snap su strade*: fai snap sui segmenti tra nodi e fermate sulle strade. Se non selezionati, i segmenti creeranno linee diritte tra nodi e fermate (es. per disegnare i percorsi delle linee ferroviarie). +- *Nascondi punti di ancoraggio alle fermate*: non mostrare punti intermedi di ancoraggio del tracciato. +- *Mostra solo segmento attivo*: visualizza su mappa solo il segmento selezionato. +- *Mostra fermate*: rendi visibili le fermate. +- *Mostra suggerimenti*: mostra suggerimenti sulle funzionalità. + +![pattern shape editing options](../../img/pattern-shape-panel.png) + +Per *modificare segmenti* di percorso già esistenti è possibile: + +- cliccare su *Modifica geometria perc.* e deselezionare *Nascondi punti di ancoraggio alle fermate*: in questo modo saranno visualizzati dei quadrati grigi in corrispondenza dei nodi di ancoraggio del percorso; +- selezionare l'arco di interesse, che sarà colorato di verde per indicare che il segmento è attivo e modificabile; +- cliccare sul quadrato di interesse (estremo del segmento) e trascinarlo fino al punto desiderato. Il quadrato diventerà nero quando selezionato. +- salvare le modifiche cliccando su *Salva*. + +![screenshot](../../img/delete-node.png) + +Per *rimuovere punti di passaggio* dal percorso è necessario cliccare sulla *X* che appare sulla geometria: il punto sarà rimosso istantaneamente e la geometria sarà modificata automaticamente. diff --git a/pages/editor/routes.md b/pages/editor/routes.md new file mode 100644 index 0000000..9b1b926 --- /dev/null +++ b/pages/editor/routes.md @@ -0,0 +1,59 @@ +--- +title: Linee +parent: Editor +nav_order: 4 +--- + +# Linee + +In questa pagina si possono trovare le informazioni inerenti le linee presenti nella base dati in analisi. + +### Modifica o crea linee + +Per modificare le linee, clicca sul tasto 🚍 sulla barra di navigazione a sinistra. +Scegli una linea dalla lista o cercala per nome nel menu a tendina. + +Per creare una nuova linea, clicca `+ Aggiungi linea`. + +![screenshot](../../img/edit-routes.png) + + +**Nota:** come tutti i nuovi oggetti creati (ad eccezione dei percorsi), la nuova linea non sarà salvata fino alla selezione del tasto `Salva` (💾). + +Per maggiori dettagli sulla creazione di una linea, è possibile consultare il seguente *video tutorial*: + +[![Creazione Linea](../../img/video-creazione-linea.png)](http://www.youtube.com/watch?v=gU6mL0u_gik "Tutorial Café 1 - Creazione Linea") + +### Zoom all'estensione della linea + +Cliccando sul tasto 🔍 (nella parte alta della toolbar) avendo una linea selezionata, sulla mappa saranno visualizzati tutti i percorsi della linea in analisi. + +### Dettagli della linea + +È necessario compilare alcuni campi obbligatori richiesti dalle specifiche GTFS: + +- *Id linea*: identificativo univoco della linea. Se non inserito dall'utente, viene creato in automatico; +- *Nome breve della linea*: nome del servizio/linea, può essere un numero; +- *Nome esteso della linea*: il nome completo della linea, spesso include origine e destinazione; +- *Tipo mezzo*: il tipo di veicolo/trasporto usato sulla linea. + +Sono inoltre disponibili alcuni campi opzionali: + +- *Azienda*: nome dell'azienda di trasporto che opera il servizio; +- *Descrizione linea*: una descrizione della linea. Attenzione a non ripetere l'informazione presente nel *nome esteso*; +- *Url della linea*: un link alla pagina web con informazioni su una specifica linea, ad esempio gli orari; +- *Colore della linea*: se una linea ha un colore associato (da usare in un calcolo percorsi ecc), può essere impostato in questo campo; +- *Colore del testo*: se una linea ha un colore da utilizzare per il testo (da usare in un calcolo percorsi ecc), può essere impostato in questo campo. + +È inoltre presente una tabella che riporta a livello di linea i km iniziali, effettivi e in proiezione calcolati a partire dalle corse previste a calendario. Per maggiori informazioni vedi la sezione [Versionamento corse](schedules). +In caso di variazioni ai percorsi e alle corse della linea è necessario cliccare il tasto `Aggiorna i dati`, in modo da visualizzare i totali km aggiornati alle ultime modifiche. + +In caso di variazioni consistenti alla linea, è possibile estrapolare dalla base dati la linea di interesse cliccando il tasto `Fai uno snapshot della linea`. Per maggiori dettagli vedi la sezione [Snapshot della linea](line_snapshot). + +Una volta compilati i campi richiesti e quelli di interesse tra quelli opzionali, clicca `Salva`. + +### Percorso + +Una volta creata e salvata la linea, è possibile iniziare a creare la traccia del percorso. + +[Impara a modificare un percorso »](patterns) diff --git a/pages/editor/schedules.md b/pages/editor/schedules.md new file mode 100644 index 0000000..95ea095 --- /dev/null +++ b/pages/editor/schedules.md @@ -0,0 +1,91 @@ +--- +title: Orari +parent: Editor +nav_order: 6 +--- + +# Orari +La sezione *Orari* è accessibile dai percorsi delle linee selezionando `Vai all'editor corse` o dal tab *Calendario*. + +L'editor corse permette agli utenti di creare/modificare corse specificando linea, percorso e calendario. + +I selettori nella parte alta della pagina permettono all'utente di navigare tra i calendari e i percorsi di una linea all'interno di un feed. +Nell'intestazione della pagina è presente l'indicazione dell'operatore che opera il servizio. + +Ogni selettore riporta una serie di informazioni aggiuntive come card: + +- **Linea** + - n° di corse per la linea selezionata. +- **Percorso** + - n° di corse per il percorso selezionato; + - lunghezza in km del percorso selezionato. +- **Calendario** + - n° di corse per il percorso selezionato; + - n° di corse attive per il calendario selezionato per il feed in analisi; + - n° di giorni di servizio per il calendario selezionato; + - link alla pagina del calendario in esame. + +Nel selettore calendario la card che indica il numero di corse di un percorso sarà evidenziata in verde se ci sono corse per la linea e il percorso selezionato. + +![schedule selector](../../img/timetable-selector.png) + +Per maggiori dettagli sull'inserimento di una corsa, è possibile consultare il seguente *video tutorial*: + +[![Inserimento Corsa](../../img/video-inserimento-corsa.png)](http://www.youtube.com/watch?v=fWzEeUzw0PE "Tutorial Café 6 - Inserimento Corsa") + +#### Barra degli strumenti degli orari +In alto a destra sullo schermo è presente una barra degli strumenti utile per effettuare alcune operazioni sugli orari: + +- *Offset corsa(e)*: specifica un offset (`HH:MM`) per impostare l'orario dell'ultima corsa nel foglio o della riga selezionata; +- *Aggiungi corsa*: aggiungi nuova corsa (primo timepoint è `00:00:00`); +- *Duplica corsa(e)*: duplica la prima corsa della tabella o la riga selezionata; +- *Elimina corsa(e)*: elimina righe selezionate; +- *Annulla tutto*: annulla tutte le modifiche; +- *Salva*: salva tutte le modifiche. + +![schedule toolbar](../../img/schedule-toolbar.png) + +#### Seleziona corse +Per selezionare una corsa per fare un offset, duplicarla o eliminarla, è sufficiente cliccare sul numero della riga nella parte sinistra della riga: la riga selezionata apparirà evidenziata in verde. Per selezionare tutte le corse, clicca la casella nell'angolo in alto a sinistra. + +![select trips](../../img/select-trips.png) + +### Modificare gli orari +Per ogni corsa è possibile modificare i seguenti campi: + +- **Codice corsa**: identificativo della corsa che rimane invariato anche in caso di versionamento della corsa; +- **Contrib**: identifica se la corsa sia o meno contribuita; +- **Km**: lunghezza in km della corsa; +- **Calendario**: indicazione del calendario a cui appartiene la corsa; +- **gg serv**: riporta il numero di giorni di servizio per il calendario a cui fa riferimento la corsa; +- **Km di linea**: lunghezza in km della corsa calcolata in base ai giorni di servizio; +- **Proiez Km**: lunghezza in km della corsa riferita all'anno solare successivo, ma calcolata con il numero di giorni di servizio dell'anno in corso (valorizzato vuoto di default, campo da compilare in caso di versionamento); +- **S**: numero di posti a sedere previsto per la corsa; +- **P**: numero di posti in piedi previsto per la corsa; +- **ac**: corse a conferma; +- **Inizia**: data di inizio validità del calendario (da valorizzare in caso di versionamento, default come da calendario o 01/01); +- **Termina**: data di fine validità del calendario (da valorizzare in caso di versionamento, default come da calendario o 31/12); +- **Orario arrivo/partenza**: orari di arrivo e partenza (partenze mostrate in grigio) per ogni fermata lungo il percorso. + +Si ricorda che viene definita corsa *a conferma* una corsa che rispetti il percorso definito di una linea, attivabile o meno in base alla richiesta dell’utenza, e corsa *a chiamata* una corsa che effettua solo le fermate pianificate secondo le prenotazioni/chiamate degli utenti. + +I chilometri delle corse indicate *ac* saranno conteggiati in un campo dedicato dei totali km. + +![editing timetables](../../img/edit-timetables.png) + +Per maggiori dettagli sulla modifica di una corsa, è possibile consultare il seguente *video tutorial*: + +[![Gestione Corse](../../img/video-gestione-corse.png)](http://www.youtube.com/watch?v=IJ9n-wK-YhE "Tutorial Café 7 - Gestione Corse") + +*Nota*: gli orari inseriti nell'editor sono riportati secondo il formato `13:00:00`. + +### Versionamento corse +Nella parte superiore della pagina `Orari` sono presenti 3 coppie di valori numerici, che varieranno in base alle modifiche effettuate nella tabella contenente le corse: + +- *Km preventivo*: km effettuati da tutte le corse del percorso nell'anno solare in corso, calcolati in base alla situazione ad inizio anno (senza tener conto dei successivi versionamenti). È presente anche l'indicazione dei km contribuiti. + +- *Km correnti*: km effettuati da tutte le corse del percorso nell'anno solare in corso, calcolati in base alla situazione attuale *di compilazione dei campi "Inizia" e "Termina"* (tenendo quindi conto delle corse versionate). È presente anche l'indicazione dei km contribuiti. + +- *Km in proiezione*: il campo riporta il numero di km che sarebbero effettuati nel caso le ultime modifiche alle corse fossero effettive per tutto l'anno solare (rappresenta una proiezione dei km sull'anno successivo, ma è calcolata con il numero di giorni di servizio dell'anno solare in analisi). È presente anche l'indicazione dei km contribuiti. + +![screenshot](../../img/version-trips.png) diff --git a/pages/editor/stops.md b/pages/editor/stops.md new file mode 100644 index 0000000..0efe115 --- /dev/null +++ b/pages/editor/stops.md @@ -0,0 +1,41 @@ +--- +title: Fermate +parent: Editor +nav_order: 3 +--- + +# Fermate + +In questa pagina si possono trovare le informazioni inerenti le fermate presenti sul territorio in cui è attivo il servizio di trasporto pubblico. + +### Informazioni sulle fermate +Per ogni fermata è necessario che alcuni campi siano compilati, come richiesto dalle specifiche GTFS: + +- *Id fermata*: identificativo univoco della fermata o stazione; +- *Nome fermata*: nome della fermata; +- *Latitudine della fermata*: latitudine della fermata; +- *Longitudine della fermata*: longitudine della fermata. + +![screenshot](../../img/add-stop.png) + +Ad ogni fermata, se non presente in fase di inserimento dei dati, sarà assegnato un id fermata univoco. + +Sono inoltre disponibili alcuni campi opzionali: + +- *Codice fermata*: numero/codice che identifica la fermata per i passeggeri; +- *Descrizione*: descrizione della fermata; +- *Url della pagina web di una fermata*: contiene la url di una pagina web della fermata; +- *Tipologia fermata*: identifica se lo stop di interesse è una fermata o una stazione; +- *Associazione a stazione*: identifica l'eventuale stazione associata ad una fermata; +- *La fermata è accessibile per un utente in sedia a rotelle*: identifica se dalla fermata in analisi è possibile per un utente in sedia a rotelle salire sul mezzo in transito. + +### Seleziona una fermata + +Scegli una fermata dalla lista o cerca per nome la fermata dal menu a tendina. +È possibile fare uno zoom sulla cartografia mentre è visibile la lista delle fermate: in questo modo appariranno sulla mappa le fermate e sarà possibile selezionarne una per visualizzare i dettagli. + +### Visualizza tutte le fermate di un feed + +Per visualizzare tutte le fermate di un feed, passa il cursore sull'icona della mappa (angolo in alto a sinistra sulla mappa) e seleziona il layer `Mostra fermate`. Una volta selezionato, saranno visibili tutte le fermate del feed (rappresentate con un cerchio in blu) anche a bassi livelli di zoom. Questo layer può essere visualizato anche se la lista delle fermate non è visibile e può essere d'aiuto in caso l'utente voglia visualizzare la posizione delle fermate lungo la linea o i percorsi di interesse. + +![screenshot](../../img/view-all-stops.png) diff --git a/pages/editor/versionamento.md b/pages/editor/versionamento.md new file mode 100644 index 0000000..b735811 --- /dev/null +++ b/pages/editor/versionamento.md @@ -0,0 +1,74 @@ +--- +title: Versionamento +parent: Editor +nav_order: 10 +--- + +# Versionamento + +Questa pagina riassume i passaggi necessari per il versionamento dei dati nell'area editor di Transit Café. + +Lo strumento permette alcune tipologie di versionamento: + +- versionamento corse: agisce sulle corse e sul loro periodo di validità; +- versionamento percorso: agisce sul percorso, sulle corse ad esso associate e sul loro periodo di validità. + +### Versionamento corse + +Questo tipo di versionamento è gestibile dalla pagina dell'editor `Orari` dopo aver selezionato la linea e il percorso di interesse. Si utilizza nelle seguenti casistiche: + +- associazione della corsa ad un differente calendario a partire da una certa data; +- modifica campo ‘Contrib’(contribuito) a partire da una certa data. + +Per procedere al versionamento di una corsa sono necessari i seguenti passaggi: + +- selezionare una o più corse da versionare cliccando sul numero della riga sulla sinistra della tabella; +- cliccare il tasto `Duplica` posizionato sotto la barra di selezione del percorso: in questo modo si creano 2 corse identiche; + +- assegnare un codice univoco al *codice corsa*: in questo campo si può concatenare una sigla che indichi il versionamento (es. -v2); + +![screenshot](../../img/trip-duplica.png) + +- compilare il campo *Inizia* con la data di inizio validità per la nuova corsa e il campo *Termina* con una data precedente a quella inserita nel campo *Inizia* per la corsa di partenza: in questo modo la corsa di origine e quella versionata avranno validità differenti; + +![screenshot](../../img/trip-version.png) + +- assegnare eventuali calendari di validità differenti o variare le informazioni inerenti le corse dove necessario. + +Nella parte superiore della pagina `Orari` sono presenti 3 coppie di valori numerici, che varieranno in base alle modifiche effettuate nella tabella contenente le corse: + +- *Km iniziali*: km effettuati da tutte le corse del percorso nell'anno solare in corso, calcolati in base alla situazione ad inizio anno (senza tener conto dei successivi versionamenti). È presente anche l'indicazione dei km contribuiti. + +- *Km effettivi*: km effettuati da tutte le corse del percorso nell'anno solare in corso, calcolati in base alla situazione attuale *di compilazione dei campi "Inizia" e "Termina"* (tenendo quindi conto delle corse versionate). È presente anche l'indicazione dei km contribuiti. + +- *Km in proiezione*: il campo riporta il numero di km che sarebbero effettuati nel caso le ultime modifiche alle corse fossero effettive per tutto l'anno solare (rappresenta una proiezione dei km sull'anno successivo, ma è calcolata con il numero di giorni di servizio dell'anno solare in analisi). È presente anche l'indicazione dei km contribuiti. + +In caso di corse indicate come *ac* sarà presente anche un record che considera i km a conferma, sottraendoli dal totale km e dai km contribuiti. + +![screenshot](../../img/version-trips.png) + +### Versionamento percorso + +Questo tipo di versionamento è gestibile dalla pagina dell'editor `Linee` dopo aver selezionato la linea e il percorso di interesse; si utilizza in caso di variazione della lunghezza contrattuale. + +Per procedere al versionamento di un percorso sono necessari i seguenti passaggi: + +- selezionare il percorso da versionare cliccando sulla linea di interesse e successivamente sul percorso che si intende modificare; + +- cliccare sul tasto dedicato al versionamento del percorso; + +![zoom](../../img/version-pattern.png) + +- selezionare la data di fine validità del percorso originale e cliccare il tasto di conferma: in questo modo viene creato un percorso duplicato con lo stesso nome a cui viene concatenato il suffisso "v2" (è possibile rinominare il percorso a piacimento). Le corse del percorso originale vengono automaticamente troncate alla data indicata; il nuovo percorso eredita tutte le corse, con validità che inizia dal giorno successivo a quello indicato. + +![zoom](../../img/pattern-version-confirm.png) + +- è quindi possibile modificare il nuovo percorso in base alle necessità, agendo sulla lunghezza contrattuale, orari, variazioni di percorso, ecc. + + +Per maggiori dettagli sul versionamento di un percorso, è possibile consultare il seguente *video tutorial*: + +[![Versionamento Percorso](../../img/video-versionamento-percorso.png)](http://www.youtube.com/watch?v=mFTtU61u7rs "Tutorial Café 4 - Versionamento Percorso") + + +Ogni tipologia di versionamento avrà effetto anche sui dati presenti nella parte manager, ma solo dopo aver eseguito uno snapshot e averlo promosso successivamente a versione: in questo modo i dati presenti nel manager rispecchieranno quelli modificati nell'editor. diff --git a/pages/introduction.md b/pages/introduction.md new file mode 100644 index 0000000..101a316 --- /dev/null +++ b/pages/introduction.md @@ -0,0 +1,32 @@ +--- +title: Introduzione +nav_order: 2 +--- + + +# Introduzione + +### Concetti generali + +Transit Café permette lo scambio di dati e il coordinamento nella creazione, aggiornamento, validazione e distribuzione di basi dati per il servizio programmato di trasporto pubblico. + +È possibile la condivisione di feed GTFS/PEA esistenti o la creazione/modifica di un feed nell'Editor. È inoltre disponibile una funzione di validazione del dato per verificare la presenza di potenziali errori. + +Una volta eseguito l'accesso al sistema, viene visualizzata una homepage che riporta: + +- un collegamento al manuale d'uso disponibile online; +- l'indicazione dell'utenza che ha eseguito l'accesso e un collegamento alla pagina del profilo dell'utente; +- un'area in cui è possibile visualizzare notifiche su eventuali basi dati osservate (vedi [Gestione progetti e feed](manager/data-manager.md)); +- un menu che permette di selezionare il progetto di interesse (in caso si sia abilitati all'accesso a più di un progetto) e l'indicazione delle basi dati presenti sullo strumento. Cliccando su una base dati si accede alle funzionalità principali di Café. + +![screenshot](../img/overview-tool.png) + +L'applicativo è costituito da 2 componenti: + +- **Manager**: fornisce informazioni di carattere generale sui dati contenuti in un PEA utilizzando contatori, diagrammi e report; + +![screenshot](../img/overview-manager.png) + +- **Editor**: permette di modificare i dati contenuti in un PEA o di crearne uno nuovo. L'interfaccia ha una forte componente cartografica. Dalla barra degli strumenti presente sulla sinistra è possibile la modifica del dato in base al tipo di informazione (aziende, fermate, linee, orari e calendari di servizio). + +![screenshot](../img/overview-editor.png) diff --git a/pages/manager/data-manager.md b/pages/manager/data-manager.md new file mode 100644 index 0000000..8662be4 --- /dev/null +++ b/pages/manager/data-manager.md @@ -0,0 +1,96 @@ +--- +title: Gestione dei dati +parent: Manager +nav_order: 1 +--- + +# Gestione dei dati + +Questa sezione fornisce informazioni generiche sui dati che compongono il PEA. Le basi dati sono suddivise in progetti, feed e snapshot, che verranno illustrati di seguito. + +### Progetti + +I progetti sono raccolte di feed e relativi versionamenti. Un progetto può, ad esempio, rappresentare una determinata area geografica e contenere tutti i contratti di servizio attivi nell'area. In Café viene associata l'icona di una cartella ad ogni progetto. + +![zoom](../img/project-vs-feed.png) + +### Feed + +Ogni feed può essere identificato con un contratto di esercizio del PEA. Per visualizzare i feed presenti in un progetto è sufficiente cliccare su `Vedi nome_progetto`. + +![screenshot](../img/overview-project.png) + +Si apre quindi una pagina contenente una tabella con la lista dei feed disponibili e alcune informazioni aggiuntive: + +- *informazioni sui feed*: riporta il nome e la data dell'ultimo aggiornamento. Può inoltre essere presente il simbolo 🔒, che indica se la base dati è stata pubblicata sul web o se è privata e disponibile solo in Café. Il default per questa opzione è *privata*; +- *stato*: fornisce informazioni sullo stato di validità del feed. Le opzioni possibili sono: attivo, in scadenza, scaduto, futuro; +- *date di validità*: indica gli estremi di validità della base dati in analisi; +- *errori*: indica la presenza di eventuali errori nel feed. Gli errori sono rilevati con riferimento alla struttura/correttezza di un file GTFS; per maggiori informazioni si prega di consultare la sezione [Errori di validazione](appendix-gtfs-warnings). + +![screenshot](../img/feed-overview.png) + +Al fondo di ogni riga della lista di feed è presente il tasto `Menu`, che permette di accedere alle seguenti opzioni: + +1. **Apri nell'Editor**: apre il feed direttamente nell'editor per poter apportare le modifiche necessarie; +2. **Aggiorna**: permette di aggiornare i feed per cui è disponibile una URL per il caricamento automatico. Questa funzionalità può essere utilizzata se è compilata la sezione *Prelievo automatico* nelle impostazioni del feed; +3. **Carica**: caricamento manuale di feed forniti da una fonte esterna al sistema o presenti in locale sul computer; +4. **Osserva**: permette di seguire gli aggiornamenti/modifiche relative ad uno specifico feed. Eventuali variazioni sulla base dati effettuate da un altro utente ad un feed osservato verranno tracciate nella homepage nella sezione `Notifiche`; +5. **Elimina**: elimina il feed caricato nel sistema e tutti i dati ad esso correlati (versioni e snapshot). + +![screenshot](../img/upload-feed.png) + + +### Versione di un feed + +Una *versione* di un feed rappresenta una variante contrattuale della base dati originale. Ogni versione ha un file GTFS associato e gestito in Transit Café: le versioni non più in uso sono visualizzabili nel navigatore di versioni e possono essere ripristinate nell'editor in ogni momento. + +Per gli utenti è inoltre disponibile un report contenente dettagli sulla validazione del dato e una pagina in cui è possibile riportare commenti sulla base dati in analisi. + +![zoom](../img/available-versions.png) + +### Snapshot + +Uno *snapshot* è una versione "di lavoro" di un set di dati e rappresenta un punto di salvataggio: può infatti essere usato come punto di partenza per modifiche future. È possibile creare uno *snapshot* cliccando sul simbolo della macchina fotografica in basso a destra nell'editor 📷. + +Gli snapshot esistenti per un determinato feed sono raccolti nel tab `Snapshot`. + +![screenshot](../img/make-snapshot.png) + +Il tasto `Ribalta` è abilitato solo per gli utenti amministratori di sistema; gli altri utenti non potranno utilizzare questa funzionalità. +Uno snapshot può diventare una versione cliccando sul tasto `Promuovi a versione` nel tab `Snapshot`: con questa operazione lo snapshot scompare dall'elenco nel tab `Snapshot` e appare con lo stesso nome nell'elenco delle versioni. + +![screenshot](../img/available-snapshots.png) + +Per maggiori dettagli sulla creazione di uno snapshot e la promozione a versione, è possibile consultare il seguente *video tutorial*: + +[![Snapshot e Versioni](../img/video-snapshot-versioni.png)](http://www.youtube.com/watch?v=RTKJdkwbokk "Tutorial Café 8 - Snapshot e Versioni") + +#### Esempio di utilizzo delle versioni e degli snapshot + +Nella cartella di lavoro è presente una base dati che rappresenta il PEA di interesse. +Vi è la necessità di modificare una linea, quindi si accede all'editor di Café. Si inizia a modificare il dato di interesse ma non si riesce a concludere il lavoro: in questo caso è consigliabile fare un salvataggio per poter riprendere il lavoro successivamente → uso uno *snapshot*. + +![zoom](../img/add-snapshot.png) + +Ci sono poi 2 possibili scenari: + +1) *Promuovi a versione*: in un secondo momento si ha la possibilità di promuovere lo snapshot a versione contrattuale. Lo snapshot diventa una versione e scompare dall'elenco. + +![zoom](../img/create-version.png) + +2) *Ripristina nell'editor*: il procedimento da seguire per riprendere da dove si era interrotto il lavoro e completare le modifiche nell'editor è: + +- cliccare sul tab `Snapshot` e selezionare lo snapshot che si era creato in precedenza; +- cliccare sul tasto `Ripristina nell'editor`; +- aprire l'editor, terminare le modifiche e creare un nuovo snapshot, +- cliccando nel tab `Snapshot` sul tasto `Promuovi a versione` si trasforma lo snapshot in versione; +- la nuova versione è accessibile dal manager. + +![zoom](../img/snapshot-toolbar.png) + +La seguente immagine riassume i possibili flussi di dati da snapshot, versioni e editor e i tasti da utilizzare. + +![zoom](../img/version-vs-snapshots-editor.png) + + +Per maggiori dettagli sulla creazione di snapshot e versioni si consiglia di consultare la sezione [Feed](managing-feeds). diff --git a/pages/manager/data-visualization.md b/pages/manager/data-visualization.md new file mode 100644 index 0000000..74105a5 --- /dev/null +++ b/pages/manager/data-visualization.md @@ -0,0 +1,40 @@ +--- +title: Visualizzazione +parent: Manager +--- + +# Visualizzazione dati del feed + +Dopo aver attivato uno snapshot/versione, dal tab *Sommario* sono visibili alcuni contatori e grafici che forniscono indicazioni sul contenuto della base dati analizzata. + +![img](../img/overview-data.png) + +I contatori forniscono informazioni su: + +- numero di aziende; +- numero di linee; +- numero di fermate; +- numero di corse; +- numero di passaggi in fermata. + +Per fornire indicazioni sul numero di corse giornaliere sono inoltre presenti due istogrammi: + +- *Numero di corse per giorno*: sull'asse delle ascisse sono indicati i giorni del calendario di validità del feed, evidenziando in blu i giorni feriali, in verde il sabato e in arancione la domenica. Sull'asse delle ordinate sono riportate le corse, raggruppate per migliaia di unità. +- *Numero di km per giorno*: sull'asse delle ascisse sono indicati i giorni di validità del calendario, evidenziando in blu i giorni feriali, in verde il sabato e in arancione la domenica. Sull'asse delle ordinate sono riportati i chilometri. + +![screenshot](../img/graph-manager.png) + +Il tab *Produzione km* contiene invece tre tabelline che riportano ciascuna: + + - numero di linee; + - numero di percorsi; + - numero di corse; + - totale km di linea (di cui urbano/extraurbano); + - totale km contribuiti (di cui urbano/extraurbano); + - totale km a conferma; + - totale posti di linea; + - totale di posti km a conferma. + +Il dato numerico è fornito per i totali di km correnti, di preventivo e quelli in proiezione. + +![img](../img/overview-progr-km.png) diff --git a/pages/manager/index.md b/pages/manager/index.md new file mode 100644 index 0000000..2226a5f --- /dev/null +++ b/pages/manager/index.md @@ -0,0 +1,11 @@ +--- +title: Manager +nav_order: 3 +--- + +# Manager + + + +Questa sezione fornisce informazioni generiche sui dati che compongono il PEA. Le basi dati sono suddivise in progetti, feed e snapshot, che verranno illustrati di seguito. + diff --git a/pages/manager/managing-feeds.md b/pages/manager/managing-feeds.md new file mode 100644 index 0000000..d66e9b3 --- /dev/null +++ b/pages/manager/managing-feeds.md @@ -0,0 +1,121 @@ +--- +title: Feed +parent: Manager +--- + +# Feed + +### Crea un feed + +Un feed può essere creato dalla pagina principale di un progetto selezionando il tasto `Azioni`. Sono disponibil diverse opzioni: + +- *Nuovo*: crea nuovo feed; +- *Aggiorna tutto*: aggiorna i feed automaticamente, utilizzabile solo se è indicata una url per il download automatico della base dati; +- *Unisci tutto*: unisce in un unico feed le basi dati presenti nel progetto; +- *Scarica il sommario come csv*: scarica come csv i dati visualizzati nella schermata. + +![screenshot](../img/actions.png) + +Cliccando sul tasto `Nuovo` si aprirà una pagina dedicata alla nuova base dati: digita il nome del feed e salva. + +È presente anche un'opzione che permette di impostare un eventuale prelievo automatico della base dati da una URL per mantenere sempre il feed aggiornato: questa opzione è sconsigliata nella modifica di un PEA. + +![screenshot](../img/create-feed.png) + +### Gestire i feed + +Dopo aver creato un feed, questo apparirà nell'elenco dei feed nel progetto: selezionandolo, si apre una pagina di dettaglio che analizza la base dati. + +Nella parte superiore della schermata sono presenti una serie di schede, che includono: + +- **Versioni**: punto di accesso ai feed; + - *Sommario della versione:* vedi informazioni sul feed, ad esempio linee, percorsi e fermate; + - *Problemi di validazione:* vedi e filtra una lista di anomalie emerse in fase di validazione; + - *Commenti alla versione:* scrivi e vedi i commenti su una specifica versione di un feed. +- **Snapshot**: lista degli snapshot (o punti di salvataggio); +- **Note**: area in cui gli utenti possono scrivere e leggere commenti su un feed; +- **Impostazioni**: accesso alle impostazioni di un feed. + +![screenshot](../img/summary-feed.png) + +Per vedere le impostazioni per uno specifico feed, clicca sul tab `Impostazioni`. Da questa sezione è possibile: + +- modificare le proprietà di base di un feed (es. nome, aggiornamento tramite URL); +- eliminare un feed (per gli utenti con particolari permessi) dall'area `Zona pericolosa`. + +![screenshot](../img/feed-settings.png) + + +### Crea una versione di un feed + +Le versioni sono create dalla pagina del feed. + +![screenshot](../img/create-version-feed.png) + +Sono disponibili tre opzioni per questa operazione: + +a. **Aggiorna da URL**: Seleziona `Recupera` dalla tendina `+ Crea nuova versione`. + +*Nota:* per recuperare una nuova versione, nel campo `Prelievo automatico del feed da URL` deve essere impostata una URL valida in `Feed → Impostazioni`. + +b. **Caricare manualmente un file**: Seleziona `Carica` dalla tendina `+ Crea nuova versione`. Clicca su `Scegli file` per selezionare un file GTFS disponibile in locale e importalo nel sistema. + +![screenshot](../img/load-version.png) + +Selezionando `Modifica feed in Editor`, si può scegliere se importare anche nella parte editor il dato presente nel manager selezionando `Importa l'ultima versione`, o se creare un nuovo file da zero e trascurare il file del manager selezionando `Inizia da zero`. + +Per utilizzare il PEA precaricato sul sistema è necessario selezionare `Importa l'ultima versione`. + +![screenshot](../img/editor-from-scratch.png) + +c. **Importa da Editor**: Seleziona `Da snapshot` dalla tendina `+ Crea nuova versione`e sarà visualizzata la lista degli snapshot disponibili per il feed in analisi. Seleziona lo snapshot desiderato e clicca il tasto `Promuovi a versione` per pubblicare lo snapshot come nuova versione. + +*Nota:* quando si carica o recupera da una URL un feed e il file caricato o recuperato non è differente dall'ultima versione, non vengono create nuove versioni del feed. + + +### Caricare versioni di un feed nell'editor + +Selezionando il tasto `Carica versione nell'Editor`, verrà importata nell'editor la versione in analisi di un feed. In caso i dati presenti nell'editor differiscano da quelli che si vogliono visionare, si aprirà una finestra popup indicante la sovrascrizione dei dati precedenti. Per poter vedere i dati aggiornati nella parte manager, è necessario caricare l'ultima versione di una base dati nell'editor. + +![screenshot](../img/load-version-editor.png) + +### Vedere e gestire versioni di un feed + +Il navigatore di versioni permette di visualizzare le versioni disponibili di un feed specifico usando i tasti `←` e `→`. Dall'interfaccia è anche possibile: + +- scaricare una versione del feed in locale in formato GTFS; +- caricare una versione nell'editor; +- eliminare una versione di un feed dal manager. (*Nota:* la cancellazione di una versione del feed non può essere annullata.) + +![screenshot](../img/feed-version-navigator.png) + +Nella parte sinistra dello schermo è presente una lista di opzioni disponibili per la versione corrente del dato, ad esempio statistiche di base sul feed, un dettagliato report di validazione e i commenti degli utenti su un feed. + +### Accesso in sola lettura + +Selezionando il tasto `Accedi in sola lettura` è possibile accedere all'editor e visualizzare la stessa base dati già aperta da un altro utente in modifica. + +![screenshot](../img/manager-read-only.png) + +Ogni feed può essere aperto e modificato nell'editor da un solo utente alla volta; viene infatti attivato un blocco temporaneo per la base dati di interesse per evitare conflitti nelle modifiche. In caso di tentativo di accesso alla stessa base dati da parte di un altra persona, verrà visualizzato un messaggio di avvertimento con l'indicazione dell'utente già attivo. Dopo 9 minuti in cui non si effettuano modifiche ai dati, il blocco viene rimosso automaticamente ed il feed torna disponibile per la modifica da parte di altri utenti. + +![zoom](../img/blocked-feed.png) + +Questa funzionalità è particolarmente utile quando 2 utenti differenti hanno necessità di aprire la stessa base dati: un utente potrà modificare il dato nell'editor, l'altro potrà accedervi ma non avrà la possibilità di salvare o modificare nulla. +L'accesso in sola lettura viene indicato nell'editor con una banda rossa attigua alla barra laterale degli strumenti. + +![screenshot](../img/read-only.png) + +Per fare in modo che l'utente in sola lettura possa visualizzare le modifiche effettuate dall'utente in scrittura, è necessario che quest'ultimo faccia uno snapshot. L'utente in lettura potrà quindi aprire nel suo editor lo snapshot di interesse e visualizzare le modifiche. + +### Ulteriori funzionalità + +Dalla pagina `Versione` si può accedere alla funzionalità di scaricamento del dato presente nel manager: + +- selezionando `Download versione`, è possibile scaricare il feed in formato *GTFS* (classico) o *GTFS +* (contenente i campi aggiuntivi previsti dal PEA); + + ![screenshot](../img/export-gtfs.png) + +- selezionando `Esporta shapefile`, è possibile scaricare in formato shapefile le fermate o la geometria dei percorsi delle linee visualizzate dal manager. + + ![screenshot](../img/export-shp.png) diff --git a/pages/manager/managing-projects.md b/pages/manager/managing-projects.md new file mode 100644 index 0000000..8ace09f --- /dev/null +++ b/pages/manager/managing-projects.md @@ -0,0 +1,32 @@ +--- +title: Progetti +parent: Manager +--- + +# Progetti + +### Creare progetti + +I progetti sono creati dalla pagina che contiene la lista dei progetti esistenti. Clicca sul tasto `Nuovo progetto` per crearne uno e apparirà una riga per il nuovo progetto creato. Digita un nome e clicca il tasto di conferma (o clicca Invio) per terminare l'operazione. + +Un nuovo progetto può essere creato solo da una utenza di tipo *Amministratore*. + +![screenshot](../img/create-project.png) + +### Gestire progetti + +Cliccando su un progetto tra quelli esistenti, si accede alla pagina contenente i dettagli del progetto. + +![screenshot](../img/project-profile.png) + +Nella parte superiore della pagina è presente il pannello `Impostazioni`, che può essere espanso per mostrare ulteriori opzioni disponibili per il progetto. Alcune delle informazioni presenti sono, ad esempio, la localizzazione dell'area geografica di interesse del progetto (specificato come singole coordinate o come area rettangolare), il fuso orario e la lingua di default. Questi valori, quando forniti, sono utilizzati per popolare le proprietà corrispondenti a livello del feed nel progetto. + +Vicino al pannello `Impostazioni` è presente il pannello `Feed`, che contiene la lista dei feed disponibili per il progetto. In questa pagina sono riportate alcune informazioni sulle basi dati in analisi: +- nome feed e ultimo aggiornamento; +- stato del feed: attivo, scaduto, in scadenza o futuro; +- date di validità del feed; +- errori di validazione: queste anomalie sono legate alla struttura del GTFS. Per maggiori informazioni consulta la pagina [1- Errori di validazione di un GTFS](appendix-gtfs-warnings) + +![screenshot](../img/project-feed-list.png) + +I feed sono il cuore di un progetto e saranno documentati in maniera dettagliata nel seguito della documentazione. diff --git a/pages/manager/managing-users.md b/pages/manager/managing-users.md new file mode 100644 index 0000000..a1744b9 --- /dev/null +++ b/pages/manager/managing-users.md @@ -0,0 +1,66 @@ +--- +title: Gestione utenti +parent: Manager +--- + + +# Gestione utenti + +### Concetti generali + +Ogni utente di Transit Café ha un account gestito tramite *Auth0*, un servizio di autenticazione di terze parti. +L'account usa un'autenticazione di tipo username-password, in cui l'indirizzo mail dell'utente è utilizzato come unico username. + +Per la creazione di nuove utenze si prega di inoltrare la richiesta a cafe@5t.torino.it. + +### Permessi dell'utente + +Transit Café utilizza un sistema di permessi utente per regolamentare l'accesso alle varie funzioni dell'applicazione. Gli utenti possono essere di tipo amministratore e non amministratore. + +##### Utenti amministratori + +Ci sono due tipi di utenza per il livello amministratore: + +- *Amministratore a livello dell'applicazione*: ha pieno accesso alle funzionalità dello strumento, incluso l'accesso a tutti i progetti e tutti i feed, la capacità di creare nuovi progetti, di creare e gestire utenti. +- *Amministratore (a livello di progetto)*: ha pieno accesso ad un singolo progetto. Non è abilitato alla creazione di nuovi progetti o all'amministrazione di utenti. + +##### Utenti non amministratori + +Per gli utenti non amministratori, i permessi possono essere assegnati su base individuale scegliendo l'opzione `Personalizzato`. I permessi di utenti non amministratori possono essere applicati solo a livello di feed in un progetto. Tutti gli utenti con accesso ad un progetto hanno accesso di sola lettura a tutti i feed del progetto come default. Selezionando il feed e/o la tipologia di permesso è possibile personalizzare ulteriormente l'accesso ai dati. I permessi disponibili sono: + +- *Gestisce configurazione feed*: possibilità di modificare le impostazioni del feed dal tab `Impostazioni`; +- *Modifica feed nell'editor*: possibilità di modificare il dato nell'editor. + +![zoom](../img/user-admin-detail.png) + +In caso non sia selezionato alcun permesso per il tipo di accesso personalizzato, l'utente potrà solo visualizzare quanto presente nel manager. + +##### Esempi permessi utente + +1. Un utente potrebbe aver bisogno di modificare i privilegi di un feed: in questo caso saranno selezionati `Modifica feed GTFS` e il feed in questione (es. Ente X). +2. Gli enti potrebbero aver bisogno di garantire l'accesso ad alcuni utenti in modo da poter visualizzare reportistica di base (visibile nella parte manager), ma senza fornirgli la possibilità di modificare o gestire nulla nell'applicativo. In questo caso, si dovrà selezionare `Personalizzato`, senza indicare altri permessi o feed. + +### Gestione utenti + +Per creare nuovi utenti, è necessario inoltrare la richiesta alla mail cafe@5t.torino.it ed indicare nome, cognome e indirizzo email della persona da abilitare allo strumento. +Una volta creata l'utenza, verrà inviata una email automatica di conferma all'indirizzo email fornito. + +## Le mie impostazioni + +### Profilo + +In questa sezione è possibile gestire alcune funzionalità legate alla singola utenza: + +- *Indirizzo email*: la mail usata come username dall'utente; +- *Avatar*: associazione di un avatar all'utente corrente utilizzando [Gravatar](http://it.gravatar.com/); +- *Password*: gestione del cambio password. + +#### Reset della password + +Hai dimenticato la password o hai bisogno di modificarla? Quando non hai ancora eseguito l'accesso, clicca su `Accedi` e poi `Non ricordo la password`. Dopo aver inserito la mail associata al tuo account utente, ti sarà inviata una mail contenente un link per resettare la password. + +![screenshot](../img/password-reset-logged-out.png) + +Hai già eseguito l'accesso, ma vuoi cambiare la password? Clicca sul'icona dell'utente (Account) in basso a sinistra nella sidebar e clicca `Il mio profilo`. Seleziona il tasto `Cambia password` per inserire il tuo indirizzo email. + +![screenshot](../img/password-reset-logged-in.png) diff --git a/pages/manager/report.md b/pages/manager/report.md new file mode 100644 index 0000000..4e6241f --- /dev/null +++ b/pages/manager/report.md @@ -0,0 +1,101 @@ +--- +title: Reportistica +parent: Manager +--- + +# Reportistica + +### Introduzione + +Dalla pagina del manager sono disponibili 3 documenti (report linee, report corse, report orari) che offrono una panoramica più completa sul servizio di trasporto descritto nei feed. Questi report sono disponibili in diversi formati: + +- **Visualizzazione web**: è possibile navigare all'interno del feed selezionando la linea di interesse; +- **Csv**: permette di effettuare ulteriori analisi sui dati del feed utilizzando un foglio elettronico; +- **Pdf**: permette di creare un file pdf da allegare ad altra documentazione. + +![img](../img/reports.png) + +### Report linee + +Il report comprende una tabella in cui sono indicate, per ogni linea appartenente al contratto di servizio analizzato, le seguenti informazioni: + +- l'azienda che opera il servizio; +- il codice numerico della linea; +- il nome per esteso della linea; +- il numero di percorsi; +- il numero di corse; +- il tipo di linea (urbana/extraurbana); +- i km della linea previsti a contratto; +- i km contribuiti della linea; +- i km a conferma. + +![img](../img/report-linee.png) + +Sopra la tabella sono inoltre posizionati alcuni tasti che permettono di scaricare i dati visualizzati su web come csv (dati correnti, di preventivo e in proiezione) e in pdf. + +Nell'intestazione del file pdf è inoltre indicato il periodo di validità del feed e il codice del contratto di servizio. + +![img](../img/report-linee-pdf.png) + + +### Report corse + +Nel report è necessario selezionare la linea di interesse (ed eventualmente il percorso), in modo da visualizzare l'azienda che effettua il servizio, il numero di km percorsi, contribuiti e a conferma. + +Per ogni percorso è inoltre indicato il codice numerico, il nome esteso, la lunghezza in km del percorso e il tipo di servizio (urbano/extraurbano). + +È possibile scaricare l'intera base dati dei percorsi del feed cliccando sul tasto `Scarica CSV completo`, oppure cliccando sul tasto `Scarica CSV della linea` saranno scaricate esclusivamente le informazioni della linea selezionata. + +Sotto il tasto `Scarica CSV completo` è presente il link `Scarica stringhe calendari` che permette di scaricare in formato csv le stringhe calendario presenti nel feed. + +![zoom](../img/download-calendar-string.png) + +Questo file contiene: + +- codice del calendario; +- n° di giorni di servizio; +- stringa composta di "1" (servizio attivo) o "0" (servizio non attivo) che descrive la frequenza del servizio. + +Se non si seleziona una linea specifica, è possibile scaricare il file csv contenente tutte le linee esercite nel contratto di servizio. + +Per ogni percorso della linea è disponibile una tabella che riporta informazioni su: + +- codice corsa; +- calendario associato alla corsa; +- n° di giorni di servizio; +- indicazione se la corsa sia o meno contribuita; +- indicazione se la corsa sia o meno a conferma; +- totale km percorsi in riferimento ai giorni di servizio di una corsa (km percorso x giorni di servizio); +- posti a sedere e posti in piedi; +- inizio e fine validità calendario, indicate in grigio se fanno riferimento all'intero anno (default 01/01 - 31/12) e in nero se fanno riferimento a corse/percorsi versionate. + +![img](../img/report-corse.png) + +Il formato csv contiene inoltre l'indicazione dei giorni della settimana in cui è operativa la corsa. + +Nell'intestazione del file pdf è indicato il periodo di validità del feed e il codice del contratto di servizio. + +![img](../img/report-corse-pdf.png) + + +### Report orari + +Nel report è necessario selezionare la linea di interesse (ed eventualmente il percorso), in modo da visualizzare l'azienda che effettua il servizio e alcune informazioni di dettaglio sulle corse. +Selezionando la linea di interesse, è possible visualizzare la lunghezza in chilometri di ogni percorso e il tipo di servizio. + +![img](../img/report-orari.png) + +Per ogni percorso della linea è disponibile una tabella che riporta informazioni su: + +- la sequenza ordinata delle fermate della corsa; +- il codice fermata; +- il nome della fermata; +- il codice corsa; +- il calendario di riferimento; +- l'orario di partenza dalla fermata. + +Il formato csv contiene inoltre l'indicazione della velocità commerciale della corsa. + +Nell'intestazione del file pdf è indicato il periodo di validità del feed e il codice del contratto di servizio. + +![img](../img/report-orari-pdf.png)