Skip to content

Commit

Permalink
Merge branch 'main' into chalin-im-tax-bc-2022-06-24
Browse files Browse the repository at this point in the history
  • Loading branch information
LisaFC authored Jul 4, 2022
2 parents 6e13d76 + e0a3be7 commit 5c6d19c
Show file tree
Hide file tree
Showing 19 changed files with 278 additions and 78 deletions.
21 changes: 15 additions & 6 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ Useful links: Docsy [releases][] & [tags][]. Jump to the [latest][] release.

For a list of issues targeted for the next release, see the [22Q2][] milestone.

## [0.4.0][] - next planned release (unpublished yet)
## [0.4.0][]

For a full list of the changes to this release, see the [release notes][0.4.0].

**Breaking changes**:

Expand Down Expand Up @@ -45,17 +47,15 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.

## [0.3.0][]

For a full list of the changes to this release, see the [release notes][0.3.0].

**Breaking changes**:

- Upgrade to [Algolia DocSearch
v3](https://docsearch.algolia.com/docs/DocSearch-v3). If your site uses the
deprecated DocSearch v2, you must [update your DocSearch
code](https://docsearch.algolia.com/docs/migrating-from-v2).

**Details**:

- See the [release notes][0.3.0]

## [0.2.0][]

**New**:
Expand All @@ -68,13 +68,22 @@ For a list of issues targeted for the next release, see the [22Q2][] milestone.

**Details**:

- See the [release notes][0.2.0]
- For a full list of the changes to this release, see the [release notes][0.2.0]

## [0.X.Y][] - next planned release (unpublished yet)

For a full list of the changes to this release, see the [release notes][0.X.Y].

**Breaking changes**:

- ...

[@deining]: https://github.com/deining
[@lisafc]: https://github.com/LisaFC
[0.2.0]: https://github.com/google/docsy/releases/v0.2.0
[0.3.0]: https://github.com/google/docsy/releases/v0.3.0
[0.4.0]: https://github.com/google/docsy/releases/v0.4.0
[0.X.Y]: #
[22q2]: https://github.com/google/docsy/milestone/3
[hugo modules]: https://gohugo.io/hugo-modules/
[latest]: https://github.com/google/docsy/releases/latest
Expand Down
71 changes: 35 additions & 36 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,57 +38,56 @@ in the Docsy user guide.
These notes are WIP for creating a release (v0.X.Y) from a local copy of the
repo.

1. Change directory to your local docsy repo and ensure that you're on a branch
1. Change directory to your local Docsy repo and ensure that you're on a branch
and at the commit that you want to tag as the next release (usually
`@HEAD`).
2. Ensure that the [CHANGELOG](CHANGELOG.md) has a release summary entry for
v0.X.Y. If not, create one with a brief summary of breaking changes. (Change
details are autogenerated by GitHub in a later step.)
3. Update the Hugo module versions to v0.X.Y.
4. Update the NPM package version in [package.json](package.json) to v0.X.Y.
5. Create the tags for v0.X.Y (we currently need two):

```console
$ REL=v0.X.Y
$ git tag $REL
$ git tag dependencies/$REL
v0.X.Y. If not, create one with a brief summary of breaking changes using
the section template at the end of the file. (Note that change details are
autogenerated by GitHub in a later step.)
3. Update the Hugo module versions to v0.X.Y.
4. Update the NPM package version in [package.json](package.json) to 0.X.Y.
5. Commit your changes, usually as a PR entitled "Release v0.X.Y preparation".
Once the PR is approved and merged, proceed with the remaining steps.
6. Create the tags for v0.X.Y (we currently need two):

```sh
REL=v0.X.Y
git tag $REL
git tag dependencies/$REL
```

6. Push the new tags to the main repo (which is named `upstream` in my setup)
either one by one or all together provided you have no other new tags
defined. The following illustrates the latter, and does a dry run first:
7. Push the new tags to the main repo (which is named `upstream` in my setup):

```console
$ git push --dry-run --tags upstream
To https://github.com/google/docsy.git
* [new tag] dependencies/v0.X.Y -> dependencies/v0.X.Y
$ git push upstream $REL && git push upstream dependencies/$REL
...
* [new tag] v0.X.Y -> v0.X.Y
* [new tag] dependencies/v0.X.Y -> dependencies/v0.X.Y
```

If only the two new tags are listed, drop the dry-run flag to push the tags.

5. Use the GitHub [Draft a new release][] feature, filling in the fields as
8. Use the GitHub [Draft a new release][] feature, filling in the fields as
follows:

- From the release/tag dropdown: Select the new release tag that you just
pushed, v0.X.Y.
- Set the release title to the release number (without the "v").
- Click "auto-generate release notes" to get the release details.
- Replace the auto-generated "## What's Changed" heading by the following:
- From the **release/tag dropdown**: Select the new release tag that you just
pushed, v0.X.Y.
- Set the **release title** to the release number (without the "v").
- Click "auto-generate release notes" to get the release details.
- Replace the auto-generated "## What's Changed" heading by the following:

```markdown
## Release summary
```markdown
## Release summary
See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
See, https://github.com/google/docsy/blob/main/CHANGELOG.md#0XY
## Commit details
```
## Commit details
```

- Replace the `0XY` anchor target above with a target appropriate for this
release.
- Remove the "New contributors" autogenerated text since we don't publish
that as part of our release notes.
- Select **Create a discussion for this release**.
- Click **Publish release**.
- Replace the `0XY` anchor target above with a target appropriate for this
release.
- Remove the "New contributors" autogenerated text (if present) since we
don't publish that as part of our release notes.
- Select **Create a discussion for this release**.
- Click **Publish release**.
[draft a new release]: https://github.com/google/docsy/releases/new
7 changes: 2 additions & 5 deletions assets/scss/_nav.scss
Original file line number Diff line number Diff line change
Expand Up @@ -153,14 +153,11 @@ nav.foldable-nav {
}

ul.foldable {
max-height: 0;
overflow: hidden;
transition: max-height 0.5s cubic-bezier(0, 1, 0, 1);
display: none;
}

input:checked ~ ul.foldable {
max-height: 100000vmax;
transition: max-height 1s ease-in-out;
display: block;
}

input[type=checkbox] { display: none; }
Expand Down
4 changes: 2 additions & 2 deletions assets/scss/shortcodes/cards-pane.scss
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.card-deck {
max-width: 83%;
@extend .td-max-width-on-larger-screens;
}
.card {
max-width: 80%;
@extend .td-max-width-on-larger-screens;
.highlight {
border: none;
}
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ go 1.12

require (
github.com/FortAwesome/Font-Awesome v0.0.0-20210804190922-7d3d774145ac // indirect
github.com/google/docsy/dependencies v0.3.0 // indirect
github.com/google/docsy/dependencies v0.4.0 // indirect
github.com/twbs/bootstrap v4.6.1+incompatible // indirect
)
2 changes: 1 addition & 1 deletion i18n/es.toml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ other = "Editar esta página"
[post_view_this]
other = "Ver código de la página"
[post_create_child_page]
other = "Create child page"
other = "Crear página nueva"
[post_create_issue]
other = "Notificar una incidencia con la documentanción"
[post_create_project_issue]
Expand Down
6 changes: 5 additions & 1 deletion layouts/partials/navbar-version-selector.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@
{{ .Site.Params.version_menu }}
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
{{ $path := "" }}
{{ if .Site.Params.version_menu_pagelinks }}
{{ $path = .Page.RelPermalink }}
{{ end }}
{{ range .Site.Params.versions }}
<a class="dropdown-item" href="{{ .url }}">{{ .version }}</a>
<a class="dropdown-item" href="{{ .url }}{{ $path }}">{{ .version }}</a>
{{ end }}
</div>
36 changes: 36 additions & 0 deletions layouts/shortcodes/conditional-text.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<!-- Get the current buildcondition from the config and lowercase it -->
{{ $condition := lower $.Site.Params.buildCondition }}

{{ if ne $condition "" }}

<!-- Get the parameters from the shortcode invocation and lowercase them.
TODO: to enable multiple conditions, we could accept comma-separated lists and split them -->
{{ $include_if := lower (.Get "include-if") }}
{{ $exclude_if := lower (.Get "exclude-if") }}

{{ if and (in $include_if $condition) (in $exclude_if $condition) }}
<!-- condition appears in both parameters -->
{{- errorf "Build condition %q appears in both include-if and exclude-if parameters of conditional-txt shortcode on page %s" $condition .Position -}}
{{ end }}

{{ if isset $.Params "include-if" }}
<!-- WARNING substring matches are matches as well! That means, if include-if="foobar", and buildcondition is "foo", you have a match!-->
{{ if in $include_if $condition }}
<!-- Do not indent the next Inner line, because the inner becomes a blockquote if the conditional-text is nested in another shortcode -->
{{ .Inner }}
{{ else }}
{{ end }}
{{ else }}

{{ if isset $.Params "exclude-if" }}
<!-- WARNING substring matches are matches as well! That means, if exclude-if="foobar", and buildcondition is "foo", you have a match!-->
{{ if in $exclude_if $condition }}
{{ else }}
<!-- Do not indent the next Inner line, because the inner becomes a blockquote if the conditional-text is nested in another shortcode -->
{{ .Inner }}
{{ end }}
{{ end }}

{{ end }}

{{ end }}
8 changes: 4 additions & 4 deletions layouts/shortcodes/imgproc.html
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@
{{ errorf "Invalid image processing command: Must be one of Fit, Fill or Resize."}}
{{ end }}
{{ $image := .Scratch.Get "image" }}
<div class="card rounded p-2 td-post-card mb-4 mt-4" style="max-width: {{ add $image.Width 10 }}px">
<figure class="card rounded p-2 td-post-card mb-4 mt-4" style="max-width: {{ add $image.Width 10 }}px">
<img class="card-img-top" src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
{{ with .Inner }}
<div class="card-body px-0 pt-2 pb-0">
<figcaption class="card-body px-0 pt-2 pb-0">
<p class="card-text">{{ . }}{{ with $image.Params.byline }}<small class="text-muted"><br/>{{ . | html }}</small>{{ end }}</p>
</div>
</figcaption>
{{ end }}
</div>
</figure>
91 changes: 91 additions & 0 deletions layouts/shortcodes/redoc.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
{{- $file := .Get 0 -}}
{{- $url := "" -}}
{{- $otheroptions := .Get 1 -}}

{{ if hasPrefix $file "http"}}
{{- $url = $file -}}
{{ else }}
{{ if (fileExists (print .Page.File.Dir $file)) -}}
<!-- First try as relative path -->
{{- $url = (print .Page.Site.BaseURL .Page.File.Dir $file) -}}
{{ else }}
<!-- Then as project-relative path-->
{{- $url = (print .Page.Site.BaseURL $file) -}}
{{- end }}
{{- end -}}

<!-- CSS style overrides for Redoc API docs -->
<style>
#redoc input { height: 64px; }
#redoc span[type="put"], span[type="get"], span[type="delete"], span[type="post"], span[type="options"], span[type="patch"], span[type="basic"], span[type="link"], span[type="head"] {
border-radius: 4px;
}
#redoc h2 { margin-top: 0px;}
</style>

<!-- Back to top button start -->
<style>
#myBtn {
display: none;
position: fixed;
bottom: 20px;
right: 30px;
z-index: 99;
font-size: 18px;
border: none;
outline: none;
background-color: #30638E;
color: white;
cursor: pointer;
padding: 15px;
border-radius: 4px;
}

#myBtn:hover {
background-color: #555;
}
</style>
<button onclick="topFunction()" id="myBtn" title="Go to top">Top</button>
<script>
//Get the button
var mybutton = document.getElementById("myBtn");

// When the user scrolls down 20px from the top of the document, show the button
window.onscroll = function() {scrollFunction()};

function scrollFunction() {
if (document.body.scrollTop > 20 || document.documentElement.scrollTop > 20) {
mybutton.style.display = "block";
} else {
mybutton.style.display = "none";
}
}

// When the user clicks on the button, scroll to the top of the document
function topFunction() {
document.body.scrollTop = 0;
document.documentElement.scrollTop = 0;
}
</script>
<!-- Back to top button end -->

<!--
Redoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>

<!--
Redoc element with link to your OpenAPI definition
-->
<div id="redoc-container">
<redoc spec-url='{{ $url }}' hide-hostname="true" suppress-warnings="true" lazy-rendering native-scrollbars scroll-y-offset=".js-navbar-scroll" {{ $otheroptions }}></redoc>
</div>
<!--
Link to Redoc JavaScript on CDN for rendering standalone element
-->
<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"></script>
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "docsy",
"version": "0.4.0-dev",
"version": "0.4.0",
"repository": "github:google/docsy",
"scripts": {
"_cd:docs": "cd userguide &&",
Expand Down
29 changes: 29 additions & 0 deletions userguide/content/en/docs/Adding content/Shortcodes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,21 @@ description: Reference for the Pet Store API

You can customize Swagger UI's look and feel by overriding Swagger's CSS or by editing and compiling a [Swagger UI dist](https://github.com/swagger-api/swagger-ui) yourself and replace `themes/docsy/static/css/swagger-ui.css`.

### redoc

The `redoc` shortcode uses the open-source [Redoc](https://github.com/Redocly/redoc) tool to render reference API documentation from an OpenAPI YAML or JSON file. This can be hosted anywhere you like, for example in your site's root [`/static` folder](/docs/adding-content/content/#adding-static-content), but you can use a URL as well, for example:

```yaml
---
title: "Pet Store API"
type: docs
weight: 1
description: Reference for the Pet Store API
---

{{</* redoc "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml" */>}}
```

### iframe

With this shortcode you can embed external content into a Docsy page as an inline frame (`iframe`) - see: https://www.w3schools.com/tags/tag_iframe.asp
Expand Down Expand Up @@ -662,3 +677,17 @@ starting with `/`. The root directory is the `/content` folder.
| code | false | Boolean value. If `true` the contents is treated as code|
| lang | plain text | Programming language |

## Conditional text

The `conditional-text` shortcode allows you to show or hide parts of your content depending on the value of the `buildCondition` parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds.

```text
{{%/* conditional-text include-if="foo" */%}}
This text appears in the output only if `buildCondition = "foo" is set in your config file`.
{{%/* /conditional-text */%}}
{{%/* conditional-text exclude-if="bar" */%}}
This text does not appear in the output if `buildCondition = "bar" is set in your config file`.
{{%/* /conditional-text */%}}
```

If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set `include-if="foobar"`, and `buildcondition = "foo"`, you have a match!
Loading

0 comments on commit 5c6d19c

Please sign in to comment.