diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index 8d8358ec46..8e37d28ea1 100644 --- a/docs/.vuepress/config/sidebar-developer.js +++ b/docs/.vuepress/config/sidebar-developer.js @@ -22,7 +22,6 @@ const developer = [ sidebarDepth: 1, children: [ ['/developer-docs/latest/setup-deployment-guides/installation/cli.md', 'CLI'], - ['/developer-docs/latest/setup-deployment-guides/typescript.md', 'TypeScript'], ['/developer-docs/latest/setup-deployment-guides/installation/docker.md', 'Docker'], [ '/developer-docs/latest/setup-deployment-guides/installation/digitalocean-one-click.md', @@ -106,7 +105,11 @@ const developer = [ '/developer-docs/latest/setup-deployment-guides/configurations/optional/rbac.md', 'Role-Based Access Control (RBAC)', ], + [ + '/developer-docs/latest/setup-deployment-guides/configurations/optional/typescript.md', + 'TypeScript', ], + ], }, ], }, @@ -223,6 +226,7 @@ const developer = [ ['/developer-docs/latest/development/admin-customization', 'Admin panel customization'], ['/developer-docs/latest/development/plugins-extension.md', 'Plugins extension'], ['/developer-docs/latest/development/plugins-development.md', 'Plugins development'], + ['/developer-docs/latest/development/typescript.md', 'TypeScript'], ], }, { diff --git a/docs/.vuepress/config/sidebar-user.js b/docs/.vuepress/config/sidebar-user.js index 9451846bd9..ce90cb2e6b 100644 --- a/docs/.vuepress/config/sidebar-user.js +++ b/docs/.vuepress/config/sidebar-user.js @@ -52,6 +52,28 @@ const user = [ ], ], }, + { + collapsable: false, + title: 'Media Library', + children: [ + [ + '/user-docs/latest/media-library/introduction-to-media-library.md', + 'Introduction to the Media Library' + ], + [ + '/user-docs/latest/media-library/adding-assets.md', + 'Adding assets' + ], + [ + '/user-docs/latest/media-library/managing-assets.md', + 'Managing individual assets' + ], + [ + '/user-docs/latest/media-library/organizing-assets-with-folders.md', + 'Organizing assets with folders' + ], + ] + }, { collapsable: false, title: 'Users, Roles & Permissions', @@ -101,4 +123,4 @@ const user = [ ], ], }, -]; \ No newline at end of file +]; diff --git a/docs/.vuepress/config/theme-config.js b/docs/.vuepress/config/theme-config.js index 92171385c3..efd2ae9d7c 100644 --- a/docs/.vuepress/config/theme-config.js +++ b/docs/.vuepress/config/theme-config.js @@ -58,6 +58,11 @@ const themeConfig = { link: '/user-docs/latest/users-roles-permissions/introduction-to-users-roles-permissions.html', }, + { + text: 'Media Library', + link: + '/user-docs/latest/media-library/introduction-to-media-library.html', + }, { text: 'Plugins', link: '/user-docs/latest/plugins/introduction-to-plugins.html', diff --git a/docs/developer-docs/latest/developer-resources/cli/CLI.md b/docs/developer-docs/latest/developer-resources/cli/CLI.md index 872b31d921..f9fca7904d 100644 --- a/docs/developer-docs/latest/developer-resources/cli/CLI.md +++ b/docs/developer-docs/latest/developer-resources/cli/CLI.md @@ -222,7 +222,7 @@ strapi admin:reset-user-password --email=chef@strapi.io --password=Gourmet1234 ## strapi generate -Run a fully interactive CLI to generate APIs, [controllers](/developer-docs/latest/development/backend-customization/controllers.md), [content-types](/developer-docs/latest/development/backend-customization/models.md), [plugins](/developer-docs/latest/development/plugins-development.md#creating-a-plugin), [policies](/developer-docs/latest/development/backend-customization/policies.md), [middlewares](/developer-docs/latest/development/backend-customization/middlewares.md) and [services](/developer-docs/latest/development/backend-customization/services.md). +Run a fully interactive CLI to generate APIs, [controllers](/developer-docs/latest/development/backend-customization/controllers.md), [content-types](/developer-docs/latest/development/backend-customization/models.md), [plugins](/developer-docs/latest/development/plugins-development.md#create-a-plugin), [policies](/developer-docs/latest/development/backend-customization/policies.md), [middlewares](/developer-docs/latest/development/backend-customization/middlewares.md) and [services](/developer-docs/latest/development/backend-customization/services.md). ```sh strapi generate diff --git a/docs/developer-docs/latest/development/typescript.md b/docs/developer-docs/latest/development/typescript.md new file mode 100644 index 0000000000..9ccf192865 --- /dev/null +++ b/docs/developer-docs/latest/development/typescript.md @@ -0,0 +1,192 @@ +--- +title: Typescript - Strapi Developer Docs +description: Learn how you can use Typescript for your Strapi application. +canonicalUrl: https://docs.strapi.io/developer-docs/latest/development/typescript.html +--- + +# TypeScript development + +::: callout 🚧 TypeScript documentation +This section is still a work in progress and will continue to be updated and improved. Migrating existing Strapi applications written in JavaScript is not currently recommended. In the meantime, feel free to ask for help on the [forum](https://forum.strapi.io/) or on the community [Discord](https://discord.strapi.io). +::: + +TypeScript adds an additional type system layer above JavaScript, which means that existing JavaScript code is also TypeScript code. Strapi supports TypeScript in new projects on v4.2.0 and above. TypeScript-enabled projects allow developing plugins with TypeScript as well as using TypeScript typings. + +::: strapi Getting started with TypeScript +To start developing in TypeScript, use the [CLI documentation](/developer-docs/latest/setup-deployment-guides/installation/cli.md) to create a new TypeScript project. Additionally, the [project structure](/developer-docs/latest/setup-deployment-guides/file-structure.md) and [TypeScript configuration](/developer-docs/latest/setup-deployment-guides/configurations/optional/typescript.md) sections have TypeScript-specific resources for understanding and configuring an application. +::: + +## Start developing in TypeScript + +Starting the development environment for a TypeScript-enabled project requires building the admin panel prior to starting the server. In development mode, the application source code is compiled to the `./dist/build` directory and recompiled with each change in the Content-type Builder. To start the application, run the following commands in the root directory: + + + + + +```sh +npm run build +npm run develop +``` + + + + + +```sh +yarn build +yarn develop +``` + + + + + +## Use TypeScript typings + +Strapi provides typings on the `Strapi` class to improve the TypeScript developing experience. These typings come with an autocomplete feature that automatically offers suggestions while developing. + +To experience TypeScript-based autocomplete while developing Strapi applications, you could try the following: + +1. From your code editor, open the `./src/index.ts` file. +2. In the `register` method, declare the `strapi` argument as of type `Strapi`: + + ```js + // path: ./src/index.ts + + import '@strapi/strapi'; + + export default { + register( { strapi }: { strapi: Strapi }) { + // ... + }, + }; + ``` + +2. Within the body of the `register` method, start typing `strapi.` and use keyboard arrows to browse the available properties. +3. Choose `runLifecyclesfunction` from the list. +4. When the `strapi.runLifecyclesFunctions` method is added, a list of available lifecycle types (i.e. `register`, `bootstrap` and `destroy`) are returned by the code editor. Use keyboard arrows to choose one of the lifecycles and the code will autocomplete. + +## Develop a plugin using TypeScript + +New plugins can be generated following the [plugins development documentation](/developer-docs/latest/development/plugins-development.md). There are 2 important distinctions for TypeScript applications: + +- After creating the plugin, run `yarn install` or `npm run install` in the plugin directory `src/admin/plugins/[my-plugin-name]` to install the dependencies for the plugin. +- Run `yarn build` or `npm run build` in the plugin directory `src/admin/plugins/[my-plugin-name]` to build the admin panel including the plugin. + +::: note +It is not necessary to repeat the `yarn install` or `npm run install` command after the initial installation. The `yarn build` or `npm run build` command is necessary to implement any plugin development that affects the admin panel. +::: + +## Start Strapi programmatically + +Instantiating Strapi programmatically in a TypeScript project requires additional configurations to load everything correctly. The primary difference for TypeScript programmatic use is that the codebase and compiled code are stored in separate directories, whereas the same directory is used to read and write in native JavaScript. + +### Understand programatic use + +When instantiating Strapi programmatically using the default export of `@strapi/strapi`, different parameters such as the `app` directory and the `dist` directory can be passed. The `app` directory is the project root directory and `dist` is a subdirectory of `app`. The `dist` directory represents the compiled project, with the same directory structure as the `app` directory, and the `app` directory represents the codebase (TypeScript or JavaScript). The main differences are: + +- When using the Content-type Builder to create, update, delete content types (or any other service that creates files), Strapi uses the `app` folder to write the files. +- When reading what content types exist on the system Strapi reads the `dist` folder. +- When the `develop` command is used only the `app` directory is watched. In TypeScript, a compilation will be triggered when a change is detected in the `app` directory and the output will be written to the `dist` directory. + +::: note +The public folder is considered static and thus ignores the `app` and `dist` directories. +::: + +The default values for the `app` and `dist` directories are transformed and assigned using one of the following options: + +```js + +const resolveWorkingDirectories = opts => { + const cwd = process.cwd(); // Neither the appDir or distDir are passed. Both the appDir and distDir are set to process.cwd(). + + const appDir = opts.appDir ? path.resolve(cwd, opts.appDir) : cwd; // Only appDir is defined distDir matches appDir. + + const distDir = opts.distDir ? path.resolve(cwd, opts.distDir) : appDir; // Only distDir is defined, appDir is set to process.cwd(). + + return { appDir, distDir }; +} + +``` + +For example, if the compiled code is stored in a separate directory (eg: when using TypeScript) Strapi should be instantiated with a specific `distDir` value which matches the path of your build directory. + +::: caution +Do not set the `appDir` to the `build` or `dist` directory as it could cause issues when the app tries to write some files. +::: + +### Start Strapi programmatically examples + +Start Strapi for JavaScript applications: + +```js +const strapi = require('@strapi/strapi'); + +strapi(); +// appDir => process.cwd() | distDir => process.cwd() + +``` + +Start Strapi using a custom `dist` directory: + +```js +const strapi = require('@strapi/strapi'); + +strapi({ distDir: './dist' }); +// appDir => process.cwd() | distDir => './dist' +``` + +Start Strapi using custom `app` and `dist` directories: + +```js + +const strapi = require('@strapi/strapi'); + +strapi({ distDir: './dist' }); +// appDir => process.cwd() | distDir => './dist' + +``` + +Start Strapi using a custom `app` directory: + +```js + +const strapi = require('@strapi/strapi'); + +strapi({ appDir: './app' }); +// appDir => './app' | distDir => './app' + +``` + +### Use both JavaScript and TypeScript codebases when starting Strapi programmatically + +Adding the package `@strapi/typescript-utils` allows for both JavaScript and TypeScript codebases to be used programatically. A common use is for creating command line interface tools or developing a plugin. Examples of how to incorporate both code bases: + +```js +const tsUtils = require('@strapi/typescript-utils'); +const strapi = require('@strapi/strapi'); + +const appDir = process.cwd(); + +// Automatically detect if this is a Typescript project: +const isTSProject = await tsUtils.isUsingTypeScript(appDir); + +// Resolve the directory containing the compilation output: +const outDir = await tsUtils.resolveOutDir(appDir); + +if (isTSProject) { +// If inside a Typescript project, compile the TypeScript code in the appDir: + await tsUtils.compile(appDir, { + watch: false, + configOptions: { options: { incremental: true } }, + }); +} + +// If inside a Typescript project, use a custom dist directory, otherwise set it to appDir value: +const distDir = isTSProject ? outDir : appDir; + +// Start the app by providing the app and dist directories: +const app = await strapi({ appDir, distDir }).load(); + +``` diff --git a/docs/developer-docs/latest/getting-started/troubleshooting.md b/docs/developer-docs/latest/getting-started/troubleshooting.md index aa431dff78..35758a8046 100644 --- a/docs/developer-docs/latest/getting-started/troubleshooting.md +++ b/docs/developer-docs/latest/getting-started/troubleshooting.md @@ -99,7 +99,7 @@ Due to these two issues, it is recommended you use a proxy application such as [ ## Can I use TypeScript in a Strapi project? -TypeScript is supported in Strapi projects from v4.2.0-beta.1 TypeScript code examples are available throughout the core Developer Documentation and a [dedicated TypeScript support page](/developer-docs/latest/setup-deployment-guides/configurations/databases/typescript.md). +TypeScript is supported in Strapi projects from v4.2.0-beta.1 TypeScript code examples are available throughout the core Developer Documentation and a [dedicated TypeScript support page](/developer-docs/latest/development/typescript.md). ## Is X feature available yet? diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md index 40b62a2950..d6ba58a529 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md @@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/setup-deployment-guid # Functions -The `./src/index.js` file (or `./src/index.ts` file in a [TypeScript-based](/developer-docs/latest/setup-deployment-guides/typescript.md) project) includes global [register](#register), [bootstrap](#bootstrap) and [destroy](#destroy) functions that can be used to add dynamic and logic-based configurations. +The `./src/index.js` file (or `./src/index.ts` file in a [TypeScript-based](/developer-docs/latest/development/typescript.md) project) includes global [register](#register), [bootstrap](#bootstrap) and [destroy](#destroy) functions that can be used to add dynamic and logic-based configurations. ## Register diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/typescript.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/typescript.md new file mode 100644 index 0000000000..170fa17031 --- /dev/null +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/typescript.md @@ -0,0 +1,17 @@ +--- +title: TypeScript configuration - Strapi Developer Docs +description: Details for TypeScript configuration +sidebarDepth: 3 +canonicalUrl: https://docs.strapi.io/developer-docs/latest/setup-deployment-guides/configurations/optional/typescript.html +--- + +# TypeScript project configuration + +[TypeScript](/developer-docs/latest/development/typescript.md)-enabled Strapi applications have a specific [project structure](/developer-docs/latest/setup-deployment-guides/file-structure.md) with the following dedicated folders and configuration files: + +| TypeScript-specific directories and files | Location | Purpose | +|-------------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `./dist` directory | application root | Adds the location for compiling the project JavaScript source code. | +| `build` directory | `./dist` | Contains the compiled administration panel JavaScript source code. The directory is created on the first `yarn build` or `npm run build` command | +| `tsconfig.json` file | application root | Manages TypeScript compilation for the server. | +| `tsconfig.json` file | `./src/admin/` | Manages TypeScript compilation for the admin panel. | diff --git a/docs/developer-docs/latest/setup-deployment-guides/file-structure.md b/docs/developer-docs/latest/setup-deployment-guides/file-structure.md index 8f55a5743c..bc1e163e72 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/file-structure.md +++ b/docs/developer-docs/latest/setup-deployment-guides/file-structure.md @@ -31,7 +31,7 @@ my-project ::: :::: -The default structure of a Strapi project created without the starter CLI depends on whether the project was created with vanilla JavaScript or with [TypeScript](/developer-docs/latest/setup-deployment-guides/typescript.md), and looks like the following: +The default structure of a Strapi project created without the starter CLI depends on whether the project was created with vanilla JavaScript or with [TypeScript](/developer-docs/latest/development/typescript.md), and looks like the following: :::: tabs card diff --git a/docs/developer-docs/latest/setup-deployment-guides/typescript.md b/docs/developer-docs/latest/setup-deployment-guides/typescript.md deleted file mode 100644 index de6dcba92a..0000000000 --- a/docs/developer-docs/latest/setup-deployment-guides/typescript.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Typescript - Strapi Developer Docs -description: Learn how you can use Typescript for your Strapi application. -canonicalUrl: https://docs.strapi.io/developer-docs/latest/setup-deployment-guides/configurations/databases/typescript.html ---- - -# TypeScript support - -::: callout 🚧 TypeScript documentation -This section is still a work in progress and will continue to be updated and improved. Migrating existing Strapi applications written in JavaScript is not currently recommended. In the meantime, feel free to ask for help on the [forum](https://forum.strapi.io/) or on the community [Discord](https://discord.strapi.io). -::: - -TypeScript adds an additional type system layer above JavaScript, which means that existing JavaScript code is also TypeScript code. Strapi supports TypeScript in new and existing projects running v4.2.0 and above. The core Developer Documentation contains code snippets in both JavaScript and TypeScript. - -## Create a new TypeScript project - -Create a Strapi project with Typescript support by using the `--ts` or `--typescript` flags with either the npm or yarn package manager. - -::: tip -Adding the `--quickstart` flag in addition to the `--ts` flag will create a TypeScript project with an [SQLite database](/developer-docs/latest/setup-deployment-guides/installation/cli.md#creating-a-strapi-project). -::: - - - - - - - -```sh -npx create-strapi-app@beta my-app --ts -#or -npx create-strapi-app@beta my-app --typescript -``` - - - - - - - -## Understand TypeScript support - -TypeScript-enabled Strapi applications have a `dist` directory at the project root and 2 `tsconfig.json` files (see [project structure](/developer-docs/latest/setup-deployment-guides/file-structure.md)). - -| TypeScript-Specific directories and files | Purpose | Location | -|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|------------------| -| `./dist` directory | Adds the location for compiling the project JavaScript source code. | application root | -| `build` directory | Contains the compiled administration panel JavaScript source code. The directory is created on the first `yarn build` or `npm run build` command | `./dist/` | -| `tsconfig.json` file | Manages TypeScript compilation for the server. | application root | -| `tsconfig.json` file | Manages TypeScript compilation for the admin panel. | `./src/admin/` | - -Starting the development environment for a TypeScript-enabled project requires building the admin panel prior to starting the server. In development mode, the application source code is compiled to the `./dist/build` directory and recompiled with each change in the Content-type Builder. To start the application run the following commands in the application root directory: - - - - - -```sh -npm run build -npm run develop -``` - - - - - -```sh -yarn build -yarn develop -``` - - - - - - - -## Develop a plugin using TypeScript - -New plugins can be generated following the [plugins development documentation](/developer-docs/latest/development/plugins-development.md). There are 2 important distinctions for TypeScript applications: - -- After creating the plugin, run `yarn install` or `npm run install` in the plugin directory `src/admin/plugins/[my-plugin-name]` to install the dependencies for the plugin. -- Run `yarn build` or `npm run build` in the plugin directory `src/admin/plugins/[my-plugin-name]` to build the admin panel including the plugin. - -::: note -It is not necessary to repeat the `yarn install` or `npm run install` command after the initial installation. The `yarn build` or `npm run build` command is necessary to implement any plugin development that affects the admin panel. -::: diff --git a/docs/package.json b/docs/package.json index bfbad4338d..1181f40ddc 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,6 +1,6 @@ { "name": "strapi-docs", - "version": "4.2.0", + "version": "4.3.0-beta", "main": "index.js", "scripts": { "dev": "yarn create:config-file && vuepress dev", diff --git a/docs/user-docs/latest/assets/icons/crop.svg b/docs/user-docs/latest/assets/icons/crop.svg new file mode 100644 index 0000000000..9a2a222e4b --- /dev/null +++ b/docs/user-docs/latest/assets/icons/crop.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/user-docs/latest/assets/icons/download.svg b/docs/user-docs/latest/assets/icons/download.svg new file mode 100644 index 0000000000..373a6a419f --- /dev/null +++ b/docs/user-docs/latest/assets/icons/download.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/user-docs/latest/assets/icons/link.svg b/docs/user-docs/latest/assets/icons/link.svg new file mode 100644 index 0000000000..56ec95fa09 --- /dev/null +++ b/docs/user-docs/latest/assets/icons/link.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/user-docs/latest/assets/icons/move.svg b/docs/user-docs/latest/assets/icons/move.svg new file mode 100644 index 0000000000..60bf412878 --- /dev/null +++ b/docs/user-docs/latest/assets/icons/move.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/user-docs/latest/assets/media-library/media-library_add-new-assets.png b/docs/user-docs/latest/assets/media-library/media-library_add-new-assets.png new file mode 100644 index 0000000000..ef47e82eab Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_add-new-assets.png differ diff --git a/docs/user-docs/latest/assets/media-library/media-library_asset-details.png b/docs/user-docs/latest/assets/media-library/media-library_asset-details.png new file mode 100644 index 0000000000..78c48506ee Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_asset-details.png differ diff --git a/docs/user-docs/latest/assets/media-library/media-library_filters.png b/docs/user-docs/latest/assets/media-library/media-library_filters.png new file mode 100644 index 0000000000..68d76f9b62 Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_filters.png differ diff --git a/docs/user-docs/latest/assets/media-library/media-library_folder-content.png b/docs/user-docs/latest/assets/media-library/media-library_folder-content.png new file mode 100644 index 0000000000..66bf153ce7 Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_folder-content.png differ diff --git a/docs/user-docs/latest/assets/media-library/media-library_move-assets.png b/docs/user-docs/latest/assets/media-library/media-library_move-assets.png new file mode 100644 index 0000000000..1c5b45e545 Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_move-assets.png differ diff --git a/docs/user-docs/latest/assets/media-library/media-library_overview.png b/docs/user-docs/latest/assets/media-library/media-library_overview.png new file mode 100644 index 0000000000..1ac701195b Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_overview.png differ diff --git a/docs/user-docs/latest/assets/media-library/media-library_sort.png b/docs/user-docs/latest/assets/media-library/media-library_sort.png new file mode 100644 index 0000000000..1c00193d97 Binary files /dev/null and b/docs/user-docs/latest/assets/media-library/media-library_sort.png differ diff --git a/docs/user-docs/latest/assets/plugins/sentry.png b/docs/user-docs/latest/assets/plugins/sentry.png index 9082ad20b6..2225be472d 100644 Binary files a/docs/user-docs/latest/assets/plugins/sentry.png and b/docs/user-docs/latest/assets/plugins/sentry.png differ diff --git a/docs/user-docs/latest/assets/settings/settings_media-library.png b/docs/user-docs/latest/assets/settings/settings_media-library.png new file mode 100644 index 0000000000..4ce012157f Binary files /dev/null and b/docs/user-docs/latest/assets/settings/settings_media-library.png differ diff --git a/docs/user-docs/latest/content-manager/writing-content.md b/docs/user-docs/latest/content-manager/writing-content.md index 614eba88ab..1d4c29a64b 100644 --- a/docs/user-docs/latest/content-manager/writing-content.md +++ b/docs/user-docs/latest/content-manager/writing-content.md @@ -27,7 +27,7 @@ To write or edit content: | Email | Write a complete and valid email address. | | Password | Write a password.

💡 Click the eye icon, displayed on the right of the box, to show the password. | | Enumeration | 1. Click the drop-down list.
2. Choose an item from the list. | -| Media | 1. Click the media area.
2. Choose an asset from the Media Library, or click the **Add more assets** button to add a new file to the Media Library.

💡 It is possible to drag and drop the chosen file in the media area. | +| Media | 1. Click the media area.
2. Choose an asset from the [Media Library](/user-docs/latest/media-library/introduction-to-media-library.md), or click the **Add more assets** button to add a new file to the Media Library.

💡 It is possible to drag and drop the chosen file in the media area. | | JSON | Write your content, in JSON format, in the code textbox. | | UID | Write a unique identifier in the textbox. A "Regenerate" button, displayed on the right of the box, allows to automatically generate a UID based on the content-type name. | diff --git a/docs/user-docs/latest/media-library/adding-assets.md b/docs/user-docs/latest/media-library/adding-assets.md new file mode 100644 index 0000000000..4067e65d7b --- /dev/null +++ b/docs/user-docs/latest/media-library/adding-assets.md @@ -0,0 +1,35 @@ +--- +title: Adding assets to the Media Library - Strapi User Guide +description: Instructions to add assets to the Media Library +canonicalUrl: https://docs.strapi.io/user-docs/latest/media-library/adding-assets.html +--- + +# Adding assets + +The Media Library displays all assets uploaded in the application, either via the [Media Library](/user-docs/latest/media-library/introduction-to-media-library.md) or the [Content Manager](/user-docs/latest/content-manager/writing-content.md#filling-up-fields) when managing a media field. + +![🏞 screenshot - "Add new assets" window](../assets/media-library/media-library_add-new-assets.png) + +To add new assets to the media library: + +1. Click the **Add new assets** button in the upper right corner of the Media Library. +2. Choose whether you want to upload the new asset from your computer or from an URL: + - from the computer, either drag & drop the asset directly or browse files on your system, + - from an URL, type or copy and paste an URL(s) in the _URL_ field, making sure multiple URLs are separated by carriage returns, then click **Next**. +3. (optional) Click the edit button ![Edit icon](../assets/icons/edit.svg) to view asset metadata and define a _File name_, _Alternative text_ and a _Caption_ for the asset (see [editing and deleting assets](managing-assets.md)). +4. (optional) Add more assets by clicking **Add new assets** and going back to step 2. +5. Click on **Upload assets to the library**. + +A variety of media types and extensions are supported by the Media Library: + +| Media type | Supported extensions | +| ---------- | --------------------------------------------------------------- | +| Image | - JPEG
- PNG
- GIF
- SVG
- TIFF
- ICO
- DVU | +| Video | - MPEG
- MP4
- MOV (Quicktime)
- WMV
- AVI
- FLV | +| Audio | - MP3
- WAV
- OGG | +| File | - CSV
- ZIP
- PDF
- XLS, XLSX
- JSON | + + + diff --git a/docs/user-docs/latest/media-library/introduction-to-media-library.md b/docs/user-docs/latest/media-library/introduction-to-media-library.md new file mode 100644 index 0000000000..3a9a22b303 --- /dev/null +++ b/docs/user-docs/latest/media-library/introduction-to-media-library.md @@ -0,0 +1,50 @@ +--- +title: Introduction to the Media Library - Strapi User Guide +description: Introduction to the Media Library which allows to display and manage all assets uploaded in the application. +canonicalUrl: https://docs.strapi.io/user-docs/latest/media-library/introduction-to-media-library.html +--- + +# Introduction to the Media Library + +The Media Library is a Strapi plugin that is always activated by default and cannot be deactivated. It is accessible both when the application is in a development and production environment. + +Administrators can access the Media Library from ![ML icon](../assets/icons/media_library.svg) _Media Library_ in the main navigation of the admin panel. + +![Media Library overview, annotated](../assets/media-library/media-library_overview.png) + +The Media Library displays all assets uploaded in the application, either via the Media Library itself or via the Content Manager when managing a media field. Assets uploaded to the Media Library can be inserted into content-types using the [Content Manager](/user-docs/latest/content-manager/writing-content.md#filling-up-fields). + +From the Media Library, it is possible to: + +- upload a new asset (see [adding assets](/user-docs/latest/media-library/adding-assets.md)) or create a new folder (see [organizing assets with folders](/user-docs/latest/media-library/organizing-assets-with-folders.md)) (1), +- sort the assets and folders or set filters (2) to find assets and folders more easily, +- make a textual search (3) to find a specific asset or folder, +- and view, navigate through, and manage folders (4). + +::: tip +Click the search icon ![Search icon](../assets/icons/search.svg) on the right side of the user interface to use a text search and find one of your assets or folders more quickly! +::: + +## Filtering assets + +Right above the list of folders and assets, on the left side of the interface, a **Filters** button is displayed. It allows setting one or more condition-based filters, which add to one another (i.e. if you set several conditions, only the assets that match all the conditions will be displayed). + +![Filters in the Media Library](../assets/media-library/media-library_filters.png) + +To set a new filter: + +1. Click on the **Filters** button. +2. Click on the 1st drop-down list to choose the field on which the condition will be applied. +3. Click on the 2nd drop-down list to choose the type of condition to apply. +4. For conditions based on the type of asset to filter, click on the 3rd drop-down list and choose a file type to include or exclude. For conditions based on date and time (i.e. _createdAt_ or _updatedAt_ fields), click on the left field to select a date and click on the right field to select a time. +5. Click on the **Add filter** button. + +::: note +When active, filters are displayed next to the **Filters** button. They can be removed by clicking on the delete icon ![Clear icon](../assets/icons/clear.svg). +::: + +## Sorting assets + +![Sort](../assets/media-library/media-library_sort.png) + +Just above the list of folders and assets, on the left side of the interface, a **Sort by** button is diplayed. It allows to display assets by upload date, alphabetical order or date of update. Click on the button and select an option in the list to automatically display the sorted assets. diff --git a/docs/user-docs/latest/media-library/managing-assets.md b/docs/user-docs/latest/media-library/managing-assets.md new file mode 100644 index 0000000000..9252493dc6 --- /dev/null +++ b/docs/user-docs/latest/media-library/managing-assets.md @@ -0,0 +1,64 @@ +--- +title: Managing assets with the Media Library - Strapi User Guide +description: Instructions on how to manage assets uploaded to the Media Library, including editing, moving, and deleting assets, and cropping images. +canonicalUrl: http://docs.strapi.io/user-docs/latest/media-library/managing-assets.html +--- + +# Managing individual assets + +The Media Library allows managing assets, which includes modifying assets' file details and location, downloading and copying the link of the assets file, and deleting assets. Image files can also be cropped. To manage an asset, click on its Edit ![Edit icon](../assets/icons/edit.svg) button. + +## Editing assets + +Clicking on the edit ![Edit icon](../assets/icons/edit.svg) button of an asset opens up a "Details" window, with all the available options. + +![Annotated asset details window screenshot](../assets/media-library/media-library_asset-details.png) + +- On the left, above the preview of the asset, control buttons (1) allow performing various actions: + - click on the delete button ![Delete icon](../assets/icons/delete.svg) to delete the asset, + - click on the download button ![Download icon](../assets/icons/download.svg) to download the asset, + - click on the copy link button ![Copy link icon](../assets/icons/link.svg) to copy the asset's link to the clipboard, + - optionally, click on the crop button ![Copy link icon](../assets/icons/crop.svg) to enter cropping mode for the image (see [cropping images](#cropping-images)). +- On the right, meta data for the asset is displayed at the top of the window (2) and the fields below can be used to update the _File name_, _Alternative text_, _Caption_ and _Asset location_ (see [organizing assets with folders](/user-docs/latest/media-library/organizing-assets-with-folders.md)) for the asset (3). +- At the bottom, the **Replace Media** button (4) can be used to replace the asset file but keep the existing content of the other editable fields, and the **Finish** button is used to confirm any updates to the fields. + +## Moving assets + +An individual asset can be moved to a folder when editing its details. + +To move an asset: + +1. Click on the edit ![Edit icon](../assets/icons/edit.svg) button for the asset to be moved. +2. In the window that pops up, click the _Asset location_ field and choose a different folder from the drop-down list. +3. Click **Save** to confirm. + +::: note +Assets can also be moved to other folders from the main view of the Media Library (see [organizing assets with folders](/user-docs/latest/media-library/organizing-assets-with-folders.md#moving-assets-to-a-folder)). This includes the ability to move several assets simultaneously. +::: + +## Cropping images + +Images can be cropped when editing the asset's details. + +To crop an image: + +1. Click on the edit ![Edit icon](../assets/icons/edit.svg) button for the asset to be cropped. +2. In the window that pops up, click the crop button ![Crop icon](../assets/icons/crop.svg) to enter cropping mode. +3. Crop the image using handles in the corners to resize the frame. The frame can also be moved by drag & drop. +4. Click the crop ![Done icon](../assets/icons/check_icon.svg) button to validate the new dimensions, and choose either to **crop the original asset** or to **duplicate & crop the asset** (i.e. to create a copy with the new dimensions while keeping the original asset untouched). Alternatively, click the stop cropping ![Cancel icon](../assets/icons/close-icon.svg) button to cancel and quit cropping mode. + +5. Click **Finish** to save changes to the file. + +## Deleting assets + +An individual asset can be deleted when editing its details. + +To delete an asset: + +1. Click on the edit ![Edit icon](../assets/icons/edit.svg) button for the asset to be deleted. +2. In the window that pops up, click the delete button ![Delete icon](../assets/icons/delete.svg) in the control buttons bar above the asset's preview. +3. Click **Confirm**. + +::: tip +Assets can also be deleted individually or in bulk from the main view of the Media Library. Select assets by clicking on their checkbox in the top left corner, then click the Delete icon ![Delete icon](../assets/icons/delete.svg) at the top of the window, below the filters and sorting options. +::: diff --git a/docs/user-docs/latest/media-library/organizing-assets-with-folders.md b/docs/user-docs/latest/media-library/organizing-assets-with-folders.md new file mode 100644 index 0000000000..4c4c0bf514 --- /dev/null +++ b/docs/user-docs/latest/media-library/organizing-assets-with-folders.md @@ -0,0 +1,81 @@ +--- +title: Adding assets to the Media Library - Strapi User Guide +description: Instructions on how to use folders in the Media Library, including adding, editing, and deleting folders, and browsing their content. +canonicalUrl: http://docs.strapi.io/user-docs/latest/media-library/organizing-assets-with-folders.html +--- + +# Organizing assets with folders + +Folders in the Media Library help you organize uploaded assets. Folders sit at the top of the Media Library view or are accessible from the Media field popup when using the [Content Manager](/user-docs/latest/content-manager/introduction-to-content-manager.md). + +From the Media Library, it is possible to view the list of folders and browse a folder's content, create new folders, edit an existing folder, move assets to a folder, and delete a folder. + +::: caution +Downgrading from Strapi v4.3.0-beta to v4.2.0 will delete folders of the Media Library. Even though assets should be preserved, we recommend you test beta versions of Strapi on a new project rather than on existing one, as unexpected consequences could impact your database. +::: + +## Browsing folders + +By default, the Media Library displays folders and assets created at the root level. Clicking a folder navigates to this folder, and displays the following elements: + +- the folder title and the number of subfolders and assets the current folder contains (1) +- the subfolders (2) the current folder contains +- all assets (3) from this folder + +![🏞 screenshot - Media library one folder deep, with back button and updated folder title](../assets/media-library/media-library_folder-content.png) + +From this dedicated folder view, folders and assets can be managed, filtered, sorted and searched just like from the main Media Library (see [introduction to Media Library](/user-docs/latest/media-library/introduction-to-media-library.md)). + +To navigate back to the parent folder, one level up, use the **Back** button at the top of the interface. + +## Adding folders + +To create a new folder in the Media Library: + +1. Click on **Add new folder** in the upper right of the Media Library interface. +2. In the window that pops up, type a name for the new folder in the _Name_ field. +3. (optional) In the _Location_ drop-down list, choose a location for the new folder. The default location is the active folder. +4. Click **Create**. + +::: note +There is no limit to how deep your folders hierarchy can go, but bear in mind it might take some effort to reach a deeply nested subfolder, as the Media Library currently has no visual hierarchy indication. Searching for files using the ![Search icon](../assets/icons/search.svg) on the right side of the user interface might be a faster alternative to finding the asset you are looking for. +::: + +## Moving assets to a folder + +Assets and folders can be moved to another folder from the root view of the Media Library or from any view for a dedicated folder. + +![🏞 screenshot - "Move elements to" popup](../assets/media-library/media-library_move-assets.png) + +To bulk move assets and folders to another folder: + +1. Select assets and folder to be moved, by clicking the checkbox on the left of the folder name or clicking the asset itself. +2. Click the ![Move icon](../assets/icons/move.svg) **Move** button at the top of the interface. +3. In the _Move elements to_ pop-up window, select the new folder from the _Location_ drop-down list. +4. Click **Move**. + +::: note +An individual asset can also be moved to a folder when [editing the asset](/user-docs/latest/media-library/managing-assets.md). +::: + +## Editing folders + +Once created, a folder can be renamed, moved or deleted. To manage a single folder: + +1. In the Folders part of the Media library, hover the folder to be edited and click its edit button ![Edit icon](../assets/icons/edit.svg). +2. In the window that pops up, update the name and location with the _Name_ field and _Location_ drop-down list, respectively. +3. Click **Save**. + +## Deleting folders + +Deleting a folder can be done either from the list of folders of the Media Library, or when editing a single folder. + +To delete a folder, from the Media Library: + +1. Click the checkbox on the left of the folder name. Multiple folders can be selected. +2. Click the ![Delete icon](../assets/icons/delete.svg) **Delete** button above the Folders list. +3. In the _Confirmation_ dialog, click **Confirm**. + +::: note +A single folder can also be deleted when editing it: hover the folder, click on its edit icon ![Edit icon](../assets/icons/edit.svg), and in the window that pops up, click the **Delete folder** button and confirm the deletion. +::: diff --git a/docs/user-docs/latest/settings/managing-global-settings.md b/docs/user-docs/latest/settings/managing-global-settings.md index 8937815ab3..6ca351ca6b 100644 --- a/docs/user-docs/latest/settings/managing-global-settings.md +++ b/docs/user-docs/latest/settings/managing-global-settings.md @@ -79,6 +79,25 @@ To add a new locale: 4. (optional) In the Advanced settings tab, tick the *Set as default locale* setting to make your new locale the default one for your Strapi application. 5. Click on the **Save** button to confirm the addition of your new locale. +## Configuring the Media Library + +The [Media Library](/user-docs/latest/media-library/introduction-to-media-library.md) displays all assets uploaded in the Strapi application. The Media Library settings allow controlling the format, file size, and orientation of uploaded assets. + +![Media Library settings](../assets/settings/settings_media-library.png) + +To configure the Media Library settings: + +1. Go to the *Global settings > Media Library* sub-section of the settings interface. +2. Define your chosen new settings: + + | Setting name | Instructions | Default value | + | -------------------------- | ---------------------------------------------------------------------------------------------------- |---------------| + | Responsive friendly upload | Enabling this option will generate multiple formats (small, medium and large) of the uploaded asset. | True | + | Size optimization | Enabling this option will reduce the image size and slightly reduce its quality. | True | + | Auto orientation | Enabling this option will automatically rotate the image according to EXIF orientation tag. | False | + +3. Click on the **Save** button. + ## Managing API tokens API tokens allow users to authenticate their Content API queries (see [Developer Documentation](/developer-docs/latest/setup-deployment-guides/configurations/optional/api-tokens.md)). Administrators can manage API tokens through the *Global settings > API Tokens* sub-section of the settings interface.