The migration guide is intended to help those using Just the Docs (as a theme or a remote theme) switch from v0.3.3 to v0.4.0.
Co-authored-by: Matt Wang <matt@matthewwang.me>
This is an alternative PR that resolves#1011. Unlike #1013, this PR defines a *new* SASS file, `_sass/custom/setup.scss`, specifically designed for new custom variables (and other SASS-only constructs). It's imported after our `support` SASS files are (functions, variables), but otherwise is imported before all other files (ex, when CSS is emitted).
So, custom callout colors can now be defined in this file. I also move the custom callout colors present in `custom.scss` to the right location.
I've added some docs that briefly explain how to use the feature. Feedback is welcome!
---
As an aside, I chose not to add a `_includes/css` file that imports this, and then import that file. I think that's only necessary if we're trying to render liquid somehow in the SASS file; since we're not trying to do that for `setup.scss`, I've opted to not include it. If we think this is relevant, I can re-add it.
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
This is a prototype for review and discussion. My use and testing of this PR is on top of 6d9d41359c46882d9b64a446d5a83fac5b3e20a7. The changes are trival to rebase to `main` and I'm happy to do so if this prototype moves forward.
* Feature request details in linked issue, fixesjust-the-docs/just-the-docs#1067
* I welcome feedback and all discussion
* A draft doc site of mine using this PR is at https://docs.hidale.com/
To use the prototype, the two include files need to be customized. Here are mine from the draft website 9c0d836408
Co-authored-by: Matt Wang <matt@matthewwang.me>
In touching up the migration guide, I noticed that many of our documentation site links are broken! For example, on the homepage, this link:
<img width="782" alt="screenshot of homepage; code snippet is in next block" src="https://user-images.githubusercontent.com/14893287/210462690-31aa7bf5-dd79-4e8f-a3c5-1213e73771c4.png">
which has the following href
```code
<a href="/just-the-docs/just-the-docs/CHANGELOG/">the CHANGELOG</a>
```
duplicates the `baseurl` twice. There are 14 such broken links across the site. Each link duplicates the `baseurl` and `link` tags, which has since been resolved with links being relative by default (there's a set of PRs that document this - I can't find the exact paper trail right now).
To resolve this, I:
- find and replace site-wide `{{ site.baseurl }}{% link` with `{% link`
- tested each link, which now works properly locally *and* on the deploy preview
I'm surprised we didn't catch this earlier! I also could be missing something else, in which case feedback on this PR is certainly welcome.
This PR corrects the change to `/_sass/search.scss` made in 551398f. This change tried to set the `padding-**top**` property to **two** values rather than set the `padding` property to these values (to represent the vertical and horizontal padding values).
I just reviewed 551398f and believe that this should be the other half of the fix proposed by just-the-docs/just-the-docs#1104.
This is a follow-up from a private maintainer discussion (https://github.com/orgs/just-the-docs/teams/maintainers/discussions/11?from_comment=12). The cliff's notes for the public are: we believe we are not currently GDPR-compliant in how the docs site itself serves analytics.
For now, we'll disable analytics; we don't use them anyways. We will then:
- add analytics and the relevant banner to the regression test repository
- in the future, workshop a built-in solution for JtD users to be GDPR compliant
- optionally, clarify the role of users of this theme (their responsibility is to make their sites GDPR compliant)(
Hi everyone, this is a large refactoring PR that looks to **modularize site components** following the discussion in #959. At the top-level, it:
- moves icons, the sidebar, header (navbar, search, aux links), footer, and mermaid components of the `default` layout into their own `_includes`
- creates a new `minimal` layout that does not render the header or sidebar as a proof-of-concept for the composability of components
- documents all existing and new layouts (including vendor code) in the "Customization" section
An important goal of this PR is for it to be **just code motion and flexibility**: there should be **zero impact** on the average end user that only consumes the `default` theme.
The next few sections go in-depth on each of the listed changes.
### new components
The `default` layout contains a "list" of all relevant components. Importantly, some of these components have sub-components:
- the header is split into the search bar, custom code, and aux links
- the icons include imports different icon components, some of which are conditionally imported by feature guards
There are also candidates for future splits and joins:
- the sidebar could be split into navigation, collections, external link, and header/footer code
- the "search footer" could be joined with other search code, which would make it easier to "include search" in one go; *however, this is a markup change*
- @kevinlin1 has pointed out that there is some leakage between the sidebar (which computes parents/grandparents) and the breadcrumbs (which needs them to render). He's graciously added a bandaid fix to `minimal` (which does not render the sidebar). However, in the long term, we should either:
- calculate this in a parent and pass the information to both components
- change how this works entirely (which may happen with multi-level navigation)
@pdmosses has done a great job outlining this and more in his [Modular Layouts test site](https://pdmosses.github.io/modular-layouts/docs/main/).
### minimal layout
Based on @kevinlin1's use-case in just-the-class (see: his [Winter 2023 CSE 373 site](https://courses.cs.washington.edu/courses/cse373/23wi/)), we've created a first-class `minimal` layout that does not render the sidebar or header.
In a [comment](https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057015039), Kevin has indicated that we can re-add the search bar in the minimal layout; however, it seems like this would be a code change. I think we should punt this to a future issue/PR.
@pdmosses has also discussed the confusion of `minimal` as a layout and its meaning in inheritance. I've added a note in documentation to clarify the (lack of) inheritance relationship.
### documentation
I've written documentation in the "Customization" page / [Custom layouts and includes](https://deploy-preview-1058--just-the-docs.netlify.app/docs/customization/#custom-layouts-and-includes) section explaining:
- generally, that we use includes/layouts (and pointing to docs)
- the `default` layout and its constituent components (with a warning about name collisions)
- creating alternative layouts with `minimal` as an example
- the inheritance chain of layouts and the vendor layouts that we consume
I've also created (and linked to) a [minimal layout test](https://deploy-preview-1058--just-the-docs.netlify.app/docs/minimal-test/) that is currently a copy of the markdown kitchen sink but with the minimal layout. I think there's room to improve this in the future.
### future work
I think there's a lot we can do. Let me break this into various sections.
Potential follow-ups before `v0.4.0`:
- re-including search in `minimal` (anticipating a minor code change)
- fixing the leakage of parent/grandparent information between the sidebar and breadcrumbs (anticipating no end-user code change, but good to evaluate separately and discuss)
- heavily document this in the migration guide (#1059) and in our RC4 release docs
- improve semantic markup for components (ex `main`, `nav`)
Related work in later minor versions:
- split up components into smaller components
- allow users to easily customize new layouts using frontmatter (see @kevinlin1's [comment in #959](https://github.com/just-the-docs/just-the-docs/issues/959#issuecomment-1249755249))
Related work for `v1.0` (i.e. a major breaking change):
- rename and better categorize existing includes
- standardizing the "custom" includes
- moving other components to the `components/` folder (ex `head`, `nav`)
- potentially: less confusing naming for various components
- potentially separate the search and header as components, so that they are completely independent
Tangentially related work:
- more flexible grid (see @JPrevost's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1363314610))
- a formal [feature model](https://en.wikipedia.org/wiki/Feature_model) of JTD, documenting feature dependence (see @pdmosses's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1365414023))
- better annotate new features (motivated by writing these docs)
- we should add "New" to new features :)
- we should note when a feature was introduced (I think this is a core part of most software documentation)
- we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge
---
Closes#959.
This PR fixes three bugs:
# first bug
When revising my last PR #1086 I realised a slight bug in the code-copy PR #945 , my change to the css ignored a case. This PR is a hotfix and
Before PR #945:
After PR #945:
Fix:
# second bug
> @simonebortolin @mattxwang I'm trying to write some regression tests for this feature.
>
> If I use GitHub's copy button to copy the following plain text, it preserves all the spaces:
>
> ```
> 1 leading space
> 2 leading spaces and 2 trailing spaces
> 3 internal spaces
> 4 trailing spaces
> ```
>
> Using the new copy button with the same text in this PR branch of JTD gives this:
>
> ```
> 1 leading space
> 2 leading spaces and 2 trailing spaces
> 3 internal spaces
> 4 trailing spaces
> ```
>
> It appears that the leading space from line 1 has been removed, and inserted on all the other lines. Moreover, the 4 trailing spaces have been removed.
>
> BTW, #924 didn't give a precise requirements spec, but mentioned the Microsoft docs UI; @mattxwang mentioned also the GitHub UI. It would be helpful to add a functional spec of what the JTD copy button is supposed to do, as a basis for regression tests.
>
> I'm not aiming at a rigorous test for the UI. Personally (using Safari at the default mag) I find the clipboard icon too small: it just looks like a box, and I can hardly see that there is a clip at the top. But I don't have a suggestion for a better icon.
# third bug
When I re-read the code after the second bug, I noticed a bug that it does not always select the text field to be copied correctly (in case there are also line numbers) is copied:
```
1
2
3
4
# Ruby code with syntax highlighting and fixed line numbers using Liquid
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
```
instead of
```
# Ruby code with syntax highlighting and fixed line numbers using Liquid
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
```
Co-authored-by: Matt Wang <matt@matthewwang.me>
This PR corrects the change to `/_sass/labels.scss` made in 551398f92fc125f4692e49d636d2625ca2bf3819. This change tried to set the `padding-**top**` property to **two** values rather than set the `padding` property to these values (to represent the vertical and horizontal padding values).
Avoid the need to add a link to favicon,ico when editing `_includes/head_custom.html`, and avoid creating an invalid favicon link
- Remove the content of `_includes/head_custom.html`
- Add code to `_includes/head.html` to create a link to an existing favicon,ico
- Add an explanation of favicon_ico to docs/configuration.md
- Remove the example of `includes/head_custom.html` and add an explanation of what the `<head>` element automatically includes
Avoid Liquid failure when no pages with titles
Fix issue #1085
The user's config specified collections (incorrectly). Trying to build the site resulted in Jekyll failing due to a Liquid error. The error report did not suggest the cause of the error.
Liquid fails with division by 0 when title_pages_size is 0. This fix guards that code by checking that title_pages is non-empty.
To test:
1. Specify a Jekyll collection with no pages, and specify it as a JTD collection.
2. Build the site.
3. Check that the specified collection has no nav links to pages.
Fix two bugs in customization docs
- custom favicon docs were not wrapped in `{% raw %}` tags
- the "new" annotation for color schemes had an extra whitespace, and so the CSS class was not applied
Context: #1074, #1076. I think the problem is likely with `@use "sass:math";`; the stock pages image doesn't contain an up-to-date enough version of SASS. I've instead replaced just that instance with a runtime `calc()` operation, which *should* get optimized away by the compiler (see: [SASS docs](https://sass-lang.com/documentation/breaking-changes/slash-div#transition-period)).
---
Original PR body:
> @pdmosses noticed that we have deprecation warnings on some of our SASS code. After testing locally, all of them have to do with using / as division in SASS, which is [deprecated](https://sass-lang.com/documentation/breaking-changes/slash-div) (since there's some lexical ambiguity).
>
> SASS has a nifty [migrator tool](https://github.com/sass/migrator). I used the migrator piecewise on each deprecation warning (since the global usage fails on some liquid code). Upon manual inspection, I think there are no false positives. Running bundle exec jekyll serve after a fresh install and bundle update no longer emits any warnings.
