From 0b55b021152c412e71267d317e1d4d7a6583f95c Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 7 Jul 2021 14:34:06 +0200 Subject: [PATCH 1/3] Add api-call, request and response custom containers --- docs/.vuepress/config.js | 51 ++++++++----- docs/.vuepress/styles/index.styl | 4 +- .../styles/strapi-custom-blocks.styl | 74 +++++++++++++++++++ 3 files changed, 109 insertions(+), 20 deletions(-) create mode 100644 docs/.vuepress/styles/strapi-custom-blocks.styl diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 4a58744d14..752d65d809 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -373,30 +373,43 @@ const checklinksIgnoredFiles = [ './developer-docs/latest/update-migration-guides/migration-guides/migration-guide-beta.20-to-3.0.0.md', // line 93 ]; +const plugins = [ + ['vuepress-plugin-element-tabs', {}], + ['@vuepress/google-analytics', { + ga: 'UA-54313258-1', + }], + ['check-md', { + ignore: checklinksIgnoredFiles, + }], + ['seo', { + siteTitle: (_, $site) => $site.title, + title: $page => $page.title, + }], + ['vuepress-plugin-code-copy', { + color: '#ffffff', + successText: 'Copied to clipboard!', + }], + ['@vuepress/back-to-top', {}], + ['vuepress-plugin-container', { + type: 'api-call', + defaultTitle: '' + }], + ['vuepress-plugin-container', { + type: 'request', + defaultTitle: 'Request' + }], + ['vuepress-plugin-container', { + type: 'response', + defaultTitle: 'Response' + }] +]; + module.exports = { title: '', port: 8080, description: 'The headless CMS developers love.', base: '/documentation/', - plugins: { - '@vuepress/medium-zoom': {}, - 'vuepress-plugin-element-tabs': {}, - '@vuepress/google-analytics': { - ga: 'UA-54313258-1', - }, - 'check-md': { - ignore: checklinksIgnoredFiles, - }, - seo: { - siteTitle: (_, $site) => $site.title, - title: $page => $page.title, - }, - 'vuepress-plugin-code-copy': { - color: '#ffffff', - successText: 'Copied to clipboard!', - }, - '@vuepress/back-to-top': {}, - }, + plugins: plugins, head: [ [ 'link', diff --git a/docs/.vuepress/styles/index.styl b/docs/.vuepress/styles/index.styl index 6e34e9968d..041f95328f 100644 --- a/docs/.vuepress/styles/index.styl +++ b/docs/.vuepress/styles/index.styl @@ -2,4 +2,6 @@ color: $accentColor !important .el-tabs__item:not(.is-disabled):hover - color: $accentColor !important \ No newline at end of file + color: $accentColor !important + +@import 'strapi-custom-blocks.styl' diff --git a/docs/.vuepress/styles/strapi-custom-blocks.styl b/docs/.vuepress/styles/strapi-custom-blocks.styl new file mode 100644 index 0000000000..1f4dc186b1 --- /dev/null +++ b/docs/.vuepress/styles/strapi-custom-blocks.styl @@ -0,0 +1,74 @@ +.custom-block + .custom-block-title + font-weight 600 + margin-bottom -0.4rem + /* + * CALLOUTS + */ + &.callout + &.callout-alt + &.strapi + &.prerequisites + padding .1rem 1.5rem + margin-top 2rem + margin-bottom 2rem + border-left-width: .25rem + border-left-style solid + &.strapi + background-color rgba(129,107,250, .05) + border-color rgb(129,107,250) + .custom-block-title + color #816bfa + font-weight 700 + p, li + color #2c3e50 + a + color #007eff + &.callout + &.callout-alt + &.prerequisites + background-color #f8f8f8 + border-color #bbbbba + &.callout-alt + border-radius: 10px + background-color: #eff5f7 + border: none + /* + * API CALLS + */ + &.api-call + background-color: rgba(250,250,250,.2) + border: solid 1px #eaeaea + border-radius: 12px + padding: .75rem 0 0 1.5rem + margin: 2rem 0 23rem + @media (min-width: 1536px) + display: flex + margin: 3rem -6rem 2rem + justify-content: space-between + .request + .extra-class + // background-color: #7a7a7a + @media (min-width: 1536px) + flex: 0 0 48% + max-width: 48% + .response + margin-top: 2rem + @media (min-width: 1536px) + margin-top: 0 + flex: 0 0 48% + p, ul + padding-right: 1rem + .custom-block-title + margin-bottom: .5rem + .request + .response + .extra-class + font-size: 90% + border-radius: 6px 0 6px 0 + pre + white-space: pre-wrap + word-break: break-word + margin-bottom: 0 +.custom-block.details + color rgb(44, 62, 80) From 4f77efd742bd69c680f3d493562537587eb1d543 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 7 Jul 2021 16:36:00 +0200 Subject: [PATCH 2/3] Fully redesign style for request & response containers --- .../styles/strapi-custom-blocks.styl | 133 ++++++++++++++++-- 1 file changed, 121 insertions(+), 12 deletions(-) diff --git a/docs/.vuepress/styles/strapi-custom-blocks.styl b/docs/.vuepress/styles/strapi-custom-blocks.styl index 1f4dc186b1..e9433c7a74 100644 --- a/docs/.vuepress/styles/strapi-custom-blocks.styl +++ b/docs/.vuepress/styles/strapi-custom-blocks.styl @@ -37,30 +37,108 @@ * API CALLS */ &.api-call - background-color: rgba(250,250,250,.2) - border: solid 1px #eaeaea + padding: 0 border-radius: 12px - padding: .75rem 0 0 1.5rem - margin: 2rem 0 23rem + margin: 2rem 0 2rem @media (min-width: 1536px) display: flex - margin: 3rem -6rem 2rem - justify-content: space-between + margin: 3rem -12rem 2rem 0 + align-items: stretch .request - .extra-class - // background-color: #7a7a7a + background-color: rgba(62,67,88,.7) + padding: 0 1rem 1rem + border-radius: 12px + font-size: 90% + color: rgba(241,251,255,.8) @media (min-width: 1536px) flex: 0 0 48% - max-width: 48% + border-radius: 12px 0 0 12px + .custom-block-title + text-transform: uppercase + margin-left: -1rem + margin-right: -1rem + margin-top: 0 + border-radius: 12px 12px 0 0 + padding: .5rem 1rem + font-weight: 400 + background-color: #373D4F + background-color: rgba(55,61,79,1) + color: #cacaca; + font-size: 90%; + @media (min-width: 1536px) + border-radius: 12px 0 0 0 + .custom-block-title+p + padding-top: 1rem + p, ul, ol + color: #2c3e50 + color: rgba(241,251,255,.8) + p + padding-left: 1rem + ul, ol + padding-left: 3rem + [class^="language-"] + background-color: transparent + font-size: 110% + pre + padding: 1rem 0 0 1rem + code + color: rgb(241,251,255) + background-color: rgba(90,90,90,.5) + .token + color: rgb(241,251,255) + &.punctuation + &.operator + color: rgba(241,251,255,.6) + &.property + color: rgb(241,251,255) + &.string + color: rgba(133, 217, 150, 1) + &.number + // color: rgb(245,106,11) + color: rgb(244,244,0) + // color: rgb(164, 205, 254) .response + background-color: rgba(220,226,234,.4) margin-top: 2rem + padding: 0 1rem 1rem + border-radius: 12px + font-size: 90% @media (min-width: 1536px) + flex: 0 0 45% margin-top: 0 - flex: 0 0 48% - p, ul - padding-right: 1rem + border-radius: 0 12px 12px 0 + .extra-class::before + color: rgba(42,64,80,.4) .custom-block-title + background-color: rgba(220,226,234,1) + border-radius: 12px 12px 0 0 + margin-left: -1rem + margin-right: -1rem + text-transform: uppercase + padding: .5rem 1rem + margin-top: 0 + font-weight: 400 + font-size: 90%; margin-bottom: .5rem + @media (min-width: 1536px) + border-radius: 0 12px 0 0 + [class^="language-"] + background-color: transparent + font-size: 110% + pre + padding: 1rem 0 0 1rem + code + .token + color: rgb(241,251,255) + &.punctuation + &.operator + color: rgba(42,64,80,.4) + &.property + color: rgba(42,64,80,.8) + &.string + color: rgba(27,137,70,1) + &.number + color: rgb(245,106,11) .request .response .extra-class @@ -72,3 +150,34 @@ margin-bottom: 0 .custom-block.details color rgb(44, 62, 80) + + +/** + * Uncomment this alternate style below + to highlight non-code text that would be + inside a request container + */ +// .custom-block +// .request +// [class^="language-"] +// &+p +// &~ol +// &~ul +// background-color: #eeeeee +// margin-left: -1rem +// margin-right: -1rem +// padding: 1rem 2rem +// color: #2c3e50 +// code +// color: #2c3e50 +// &~ol +// &~ul +// padding: 1rem 4rem +// &+p+ol +// &+p+ul +// margin-top: -1rem +// &~ol:last-of-type +// &~ul:last-of-type +// &~p:last-of-type +// margin-bottom: -1.5rem +// border-radius: 0 0 12px 12px From d738becd8c14c734d208be3c2823b7afa4369cba Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Wed, 7 Jul 2021 19:15:52 +0200 Subject: [PATCH 3/3] Use api-callout container on existing documentation --- .../content-api/content-api.md | 88 ++++------- .../latest/development/plugins/i18n.md | 139 ++++++------------ 2 files changed, 68 insertions(+), 159 deletions(-) diff --git a/docs/developer-docs/latest/developer-resources/content-api/content-api.md b/docs/developer-docs/latest/developer-resources/content-api/content-api.md index 80d26632d1..a29cf12589 100644 --- a/docs/developer-docs/latest/developer-resources/content-api/content-api.md +++ b/docs/developer-docs/latest/developer-resources/content-api/content-api.md @@ -299,21 +299,15 @@ Here are some Content Type examples Returns entries matching the query filters. You can read more about parameters [here](#api-parameters). -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```js -GET http://localhost:1337/restaurants -``` +`GET http://localhost:1337/restaurants` ::: -::: tab Response - -**Example response** +::: response Example response ```json [ @@ -382,21 +376,15 @@ GET http://localhost:1337/restaurants Returns an entry by id. -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```js -GET http://localhost:1337/restaurants/1 -``` +`GET http://localhost:1337/restaurants/1` ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -463,25 +451,17 @@ GET http://localhost:1337/restaurants/1 Returns the count of entries matching the query filters. You can read more about parameters [here](#api-parameters). -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```js -GET http://localhost:1337/restaurants/count -``` +`GET http://localhost:1337/restaurants/count` ::: -::: tab Response +::: response Example response -**Example response** - -``` -1 -``` +`1` ::: @@ -493,15 +473,11 @@ Creates an entry and returns its value. If the [Internationalization (i18n) plugin](/developer-docs/latest/development/plugins/i18n.md) is installed, it's possible to use POST requests to the Content API to [create localized entries](/developer-docs/latest/development/plugins/i18n.md#creating-a-new-localized-entry). -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```js -POST http://localhost:1337/restaurants -``` +`POST http://localhost:1337/restaurants` ```json { @@ -532,9 +508,7 @@ POST http://localhost:1337/restaurants ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -607,15 +581,11 @@ Fields that aren't sent in the query are not changed in the database. Send a `nu It's currently not possible to [update the locale of an entry](/developer-docs/latest/development/plugins/i18n.md#updating-an-entry). ::: -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```js -PUT http://localhost:1337/restaurants/1 -``` +`PUT http://localhost:1337/restaurants/1` ```json { @@ -655,9 +625,7 @@ PUT http://localhost:1337/restaurants/1 ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -730,21 +698,15 @@ PUT http://localhost:1337/restaurants/1 Deletes an entry by id and returns its value. -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```js -DELETE http://localhost:1337/restaurants/1 -``` +`DELETE http://localhost:1337/restaurants/1` ::: -::: tab Response - -**Example response** +::: response Example response ```json { diff --git a/docs/developer-docs/latest/development/plugins/i18n.md b/docs/developer-docs/latest/development/plugins/i18n.md index a7511b32ff..e73463a7d1 100644 --- a/docs/developer-docs/latest/development/plugins/i18n.md +++ b/docs/developer-docs/latest/development/plugins/i18n.md @@ -109,22 +109,15 @@ When the i18n plugin is installed, the response to requests includes fields that - `locale`(string) is the locale code for the localized content entry - `published_at` (string) is the date and time when the localized content entry was [published](/developer-docs/latest/concepts/draft-and-publish.md#publishing-a-draft), in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format +:::: api-call -:::: tabs - -::: tab Request +::: request Example request -**Example request** - -```http -GET http://localhost:1337/restaurants?_locale=fr -``` +`GET http://localhost:1337/restaurants?_locale=fr` ::: -::: tab Response - -**Example response** +::: response Example Response ```json [ @@ -151,12 +144,13 @@ GET http://localhost:1337/restaurants?_locale=fr ] ``` +::: +:::: + In the example response above: - restaurant with `"id": 4` is a French (`"locale": "fr"`) localization of the existing restaurant with `"id": 3` (created for the default `en` locale), as shown in the `localizations` object included in the response (see [creating a localization for an existing entry](#creating-a-localization-for-an-existing-entry)). - restaurant with `"id": "8"` was created from scratch using the API, passing the `locale: fr` in the request body (see [creating a new localized entry](#creating-a-new-localized-entry)). -::: -:::: ### Creating a new localized entry @@ -164,14 +158,10 @@ To create a localized entry from scratch, send a POST request to the Content API If no locale has been passed in the request body, the entry is created using the default locale for the application: -:::: tabs -::: tab Request - -**Example request** +:::: api-call +::: request Example request -```http -POST http://localhost:1337/restaurants -``` +`POST http://localhost:1337/restaurants` ```json { @@ -182,9 +172,7 @@ POST http://localhost:1337/restaurants ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -201,14 +189,10 @@ POST http://localhost:1337/restaurants To create a localized entry for a locale different from the default one, add the `locale` attribute to the body of the POST request: -:::: tabs -::: tab Request +:::: api-call +::: request Example request -**Example request** - -```http -POST http://localhost:1337/restaurants -``` +`POST http://localhost:1337/restaurants` ```json { @@ -220,8 +204,7 @@ POST http://localhost:1337/restaurants ::: -::: tab Response -**Example response** +::: response Example response ```json { @@ -258,20 +241,17 @@ When sending a POST request to a collection type, Strapi will: 1. use the `id` as a base entry for the non-localized fields and copy them in the new entry 2. then create a new entry for the given locale and link it with the base entry. -:::: tabs - -::: tab Request +:::: api-call -**Example request** +::: request Example request -```http -POST http://localhost:1337/restaurants/8/localizations -``` +`POST http://localhost:1337/restaurants/8/localizations` ```json { "locale": "en", "name": "She's Cake", + "test": 9, "description": "She's Cake restaurant description in English" } ``` @@ -281,12 +261,9 @@ This request: 1. creates a new entry in `en` 2. links the created entry with `restaurant:8` (they will share the same `localizations` object) 3. copies every non-localized fields from `restaurant:8` into the new entry and keeps the localized fields from the request's body - ::: -::: tab Response - -**Example reponse** +::: response Example reponse ```json { @@ -308,17 +285,14 @@ This request: :::: + #### Creating a localization for a single type -:::: tabs +:::: api-call -::: tab Request +::: request Example request -**Example request** - -```http -POST http://localhost:1337/homepage/localizations -``` +`POST http://localhost:1337/homepage/localizations` ```json { @@ -329,9 +303,7 @@ POST http://localhost:1337/homepage/localizations ::: -::: tab Response - -**Example reponse** +::: response Example reponse ```json { @@ -377,11 +349,9 @@ To fetch entries for all locales, use `locale: "all"` in the query. ::: #### Fetching a collection type -:::: tabs +:::: api-call -::: tab Query - -**Example query** +::: request Example query ```graphql query { @@ -399,9 +369,7 @@ query { ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -445,11 +413,9 @@ query { :::: #### Fetching a single type -:::: tabs - -::: tab Query +:::: api-call -**Example query** +::: request Example query ```graphql query { @@ -467,9 +433,7 @@ query { ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -501,11 +465,9 @@ The `locale` field can be passed in the `data` object of the mutation to create #### Creating a new localization for a collection type -:::: tabs +:::: api-call -::: tab Mutation - -**Example mutation** +::: request Example mutation ```graphql mutation { @@ -531,9 +493,7 @@ mutation { ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -562,11 +522,9 @@ mutation { #### Creating a new localization for a single type -:::: tabs - -::: tab Mutation +:::: api-call -**Example mutation** +::: request Example mutation ```graphql mutation { @@ -592,9 +550,7 @@ mutation { ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -624,11 +580,9 @@ A `locale` argument can be passed in the mutation to update content for a given Currently, it is not possible to change the locale of an existing localized entry. If you set a `locale` field in the `data` object of the mutation, it will be ignored. -:::: tabs - -::: tab Mutation +:::: api-call -**Example mutation** +::: request Example mutation ```graphql mutation { @@ -647,9 +601,7 @@ mutation { ::: -::: tab Response - -**Example response** +::: response Example response ```json { @@ -665,18 +617,15 @@ mutation { ``` ::: - :::: ### Deleting a localization for a single type with GraphQL Pass the `locale` argument in the mutation to delete a specific localization for a single type: -:::: tabs - -::: tab Mutation +:::: api-call -**Example mutation** +::: request Example mutation ```graphql mutation { @@ -691,9 +640,7 @@ mutation { ::: -::: tab Response - -**Example response** +::: response Example response ```json {