> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/latex/ru/drugie-temy/27-inserting-images.md). # Вставка изображений ## Четыре способа вставки изображений (создания фигур LaTeX) в Overleaf Варианты следующие: 1. Используйте [**Вставить рисунок** кнопку](https://learn.overleaf.com/learn/Kb/How_to_insert_figures_in_Overleaf#Using_Insert_Figure_to_add_a_figure_to_your_project)(![The Insert Figure button on the editor toolbar](/files/5db2d359848838504944c42e38a59099141fb0d6)), расположенную на панели инструментов редактора, чтобы вставить рисунок в **Визуальный редактор** или **Кодовый редактор**. 2. [Скопировать и вставить изображение](/latex/ru/baza-znanii/075-how-to-paste-formatted-content-into-overleaf.md#pasting-images-into-your-overleaf-project) в **Визуальный редактор** или **Кодовый редактор**. 3. Вы можете использовать перетаскивание, чтобы создать рисунок. Выберите файл из локальной файловой системы или один из файлов, загруженных в ваш проект Overleaf, и перетащите его в **Визуальный редактор** или **Кодовый редактор**. Overleaf отображает окно с параметрами для настройки вашего рисунка. 4. Используйте **Кодовый редактор** чтобы написать код LaTeX, который вставляет графику и помещает её внутри окружения figure. Параметры 1, 2 и 3 автоматически генерируют код LaTeX, необходимый для создания вашего рисунка, но здесь мы рассматриваем вариант 4, который предоставляет наибольшую гибкость. ## Введение В этой статье мы объясняем, как включать изображения в самых распространённых форматах, как уменьшать, увеличивать и поворачивать их, а также как ссылаться на них внутри вашего документа. Мы начнём с примера, демонстрирующего, как импортировать изображение. ```latex \documentclass{article} \usepackage{graphicx} \graphicspath{ {./images/} } \begin{document} Вселенная огромна, и кажется, что она однородна, в больших масштабах, везде, куда бы мы ни посмотрели. \includegraphics{universe} Сверху показано изображение галактики \end{document} ``` ![Пример вставки изображения](/files/f21a16d17932aeca45b8bd9eff5764b9b28cdfc9) Latex не может самостоятельно работать с изображениями, поэтому нам нужно использовать пакет `graphicx` . Чтобы использовать его, мы включаем следующую строку в преамбулу: `\usepackage{graphicx}`. Команда `\graphicspath{ {./images/} }` сообщает LaTeX, что изображения хранятся в папке с именем `images` в каталоге основного документа. Это `\includegraphics{universe}` команда — это та, которая фактически включила изображение в документ. Здесь `universe` — это имя файла, содержащего изображение, без расширения, тогда `universe.PNG` становится `universe`. Имя файла изображения не должно содержать пробелов и нескольких точек. Примечание: расширение файла можно указывать, но лучше его опускать. Если расширение файла не указано, LaTeX будет искать все поддерживаемые форматы. Подробнее см. раздел о [создании изображений высокого и низкого разрешения](#generating-high-res-and-low-res-images). [Откройте пример изображений в Overleaf](https://www.overleaf.com/project/new/template/19397?id=65443742\&templateName=Inserting+Images\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## Путь к папке с изображениями При работе с документом, который включает несколько изображений, можно хранить эти изображения в одной или нескольких отдельных папках, чтобы проект был более организованным. Команда `\graphicspath{ {images/} }` сообщает LaTeX искать в `images` папке. Путь ***относительный*** к текущему рабочему каталогу — поэтому компилятор будет искать файл в той же папке, где находится код, в который включено изображение. Путь к папке по умолчанию относительный, если не указан начальный каталог, например ```latex %Путь относительно .tex-файла, содержащего команду \includegraphics \graphicspath{ {images/} } ``` Обычно это простой способ добраться до папки с графикой в дереве файлов, но он может приводить к осложнениям, когда `.tex` файлы внутри папок включаются в основной `.tex` файл. Тогда компилятор может начать искать папку с изображениями не там, где нужно. Поэтому **лучшая практика — указывать путь к графике относительно основного `.tex` файла**, обозначая основной `.tex` каталог файла как `./` , например: ```latex %Путь относительно основного .tex-файла \graphicspath{ {./images/} } ``` как во введении. Путь также может быть ***абсолютным***, если указано точное расположение файла в вашей системе. Например, если вы работаете с локальной установкой LaTeX на своём компьютере: ```latex %Путь в формате Windows: \graphicspath{ {c:/user/images/} } %Путь в Unix-подобном формате (Linux, Mac OS) \graphicspath{ {/home/user/images/} } ``` Обратите внимание, что эта команда требует завершающего слэша `/` и что путь находится между двойными фигурными скобками. Вы также можете задать несколько путей, если изображения сохранены более чем в одной папке. Например, если есть две папки с именами `images1` и `images2`, используйте команду ```latex \graphicspath{ {./images1/}{./images2/} } ``` [Откройте пример изображений в Overleaf](https://www.overleaf.com/project/new/template/19397?id=65443742\&templateName=Inserting+Images\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## Изменение размера изображения и поворот рисунка Если мы хотим дополнительно указать, как именно LaTeX должен включать наше изображение в документ (длина, высота и т. д.), мы можем передать эти настройки в следующем формате: ```latex \begin{document} Overleaf — отличный профессиональный инструмент для редактирования документов онлайн, совместного использования и резервного копирования ваших проектов \LaTeX{}. Также предлагает довольно большую справочную документацию. \includegraphics[scale=1.5]{overleaf-logo} ``` ![Пример изменения размера изображения](/files/99e9a63a641a5de1da6168643003f78ed5072f3d) Команда `\includegraphics[scale=1.5]{overleaf-logo}` вставит изображение `overleaf-logo` в документ, дополнительный параметр `scale=1.5` сделает именно это: масштабирует изображение до 1.5 от его реального размера. Вы также можете масштабировать изображение до определённой ширины и высоты. ```latex \begin{document} Overleaf — отличный профессиональный инструмент для редактирования документов онлайн, совместного использования и резервного копирования ваших проектов \LaTeX{}. Также предлагает довольно большую справочную документацию. \includegraphics[width=5cm, height=4cm]{overleaf-logo} ``` ![Пример задания высоты и ширины изображения](/files/f38cb9aa3d28da46e809ac10c9341261bf3bc92f) Как вы, вероятно, уже догадались, параметры в квадратных скобках `[width=3cm, height=4cm]` определяют ширину и высоту картинки. Вы можете использовать [разные единицы измерения](#reference-guide) для этих параметров. Если передан только *ширина* параметр, высота будет масштабирована с сохранением пропорций. Единицы длины также могут быть относительными по отношению к некоторым элементам документа. Если вы хотите, например, сделать картинку такой же ширины, как текст: ```latex \begin{document} Вселенная огромна, и кажется, что она однородна, в больших масштабах, везде, куда бы мы ни посмотрели. \includegraphics[width=\textwidth]{universe} ``` ![Пример изображения, заданного по ширине текста](/files/88c5f88b48ddf3e370340070a5067bd509ad813f) Вместо `\textwidth` вы можете использовать любую другую стандартную длину LaTeX: `\columnsep`, `\linewidth`, `\textheight`, `\paperheight`, и т. д. См. [справочное руководство](#reference-guide) для более подробного описания этих единиц. Есть ещё один распространённый вариант при включении изображения в документ — повернуть его. В LaTeX это легко сделать: ```latex \begin{document} Overleaf — отличный профессиональный инструмент для редактирования онлайн, совместного использования и резервного копирования ваших проектов \LaTeX{}. Также предлагает довольно большая база справочной документации. \includegraphics[scale=1.2, angle=45]{overleaf-logo} ``` ![Пример поворота изображения](/files/1edbed68b39445e7e51d4af4f3aa9d7fbf1b32e0) Параметр `angle=45` поворачивает картинку на 45 градусов против часовой стрелки. Чтобы повернуть картинку по часовой стрелке, используйте отрицательное число. ## Размещение В предыдущем разделе было объяснено, как включать изображения в ваш документ, но сочетание текста и изображений может выглядеть не так, как мы ожидали. Чтобы изменить это, нам нужно ввести новое *окружения*. ```latex В следующем примере рисунок будет размещён прямо под этим предложением. \begin{figure}[h] \includegraphics[width=8cm]{Plot} \end{figure} ``` ![Пример размещения рисунков](/files/ae055a6abbf437849d90ce28001bd9cd92121a55) Это `figure` окружение используется для отображения изображений как плавающих элементов внутри документа. Это означает, что вы помещаете изображение внутрь `figure` окружения и вам не нужно беспокоиться о его размещении: LaTeX расположит его так, чтобы оно вписывалось в поток документа. Тем не менее, иногда нам нужен больший контроль над тем, как отображаются рисунки. Можно передать дополнительный параметр, чтобы определить размещение рисунка. В примере `begin{figure}[h]`, параметр в квадратных скобках задаёт положение рисунка как ***здесь***. Ниже приведена таблица возможных значений размещения. | Параметр | Положение | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | h | Разместить плавающий объект *здесь*, то есть *примерно* в том же месте, где он находится в исходном тексте (однако не *точно* в этом месте) | | t | Разместить в *верхней части* страницы. | | b | Разместить в *нижняя часть* страницы. | | p | Поместить на специальную *страницу* только для плавающих объектов. | | ! | Переопределяет внутренние параметры, которые LaTeX использует для определения «хороших» позиций плавающих объектов. | | H | Размещает плавающий объект точно в том месте, где он указан в коде LaTeX. Требует пакет `float` пакет, хотя иногда может вызывать проблемы. Это в некотором смысле эквивалентно h!. | В следующем примере вы можете увидеть изображение в `t`верхней части документа, несмотря на то, что оно объявлено ниже текста. ```latex На этом рисунке вы можете увидеть столбчатую диаграмму, показывающую результаты опроса, в котором участвовали некоторые важные данные, изучавшиеся с течением времени. \begin{figure}[t] \includegraphics[width=8cm]{Plot} \centering \end{figure} ``` ![Пример столбчатой диаграммы](/files/59b0bef50dbb9d8520700457afc628ce3b663f44) Дополнительная команда `\centering` центрирует картинку. Значение выравнивания по умолчанию — *левый*. ### Обтекание рисунков текстом Также можно **wrap** обтекать текстом рисунок. Когда документ содержит небольшие изображения, это выглядит лучше. ```latex \begin{wrapfigure}{r}{0.25\textwidth} %это изображение будет справа \centering \includegraphics[width=0.25\textwidth]{mesh} \end{wrapfigure} Есть несколько способов построить функцию двух переменных, в зависимости от информации, которая вас интересует. Например, если вы хотите увидеть сетку функции, чтобы проще увидеть производную, вы можете использовать график, как тот, что слева. \begin{wrapfigure}{l}{0.25\textwidth} \centering \includegraphics[width=0.25\textwidth]{contour} \end{wrapfigure} С другой стороны, если вас интересуют только определённые значения, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, как тот, что слева. С другой стороны, если вас интересуют только определённые значения, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, вы можете использовать контурный график, как тот, что слева. ``` ![Пример графика](/files/120f106111c08da9ac44871bd3612cb21deeb19f) Чтобы команды в примере работали, вам нужно импортировать [`wrapfig` пакет](https://ctan.org/pkg/wrapfig?lang=en). Чтобы использовать `wrapfig`, включите следующую строку в преамбулу документа: ```latex \usepackage{wrapfig} ``` Это делает `wrapfigure` окружение доступным, и мы можем поместить внутрь него `\includegraphics` команду, чтобы создать рисунок, вокруг которого будет обтекание текста. Вот как мы можем задать *wrapfigure* среду: ```latex \begin{wrapfigure}[lineheight]{position}{width} ... \end{wrapfigure} ``` Это `position` параметр имеет восемь возможных значений: | | | | | --- | - | ------------------------------------------------------------ | | r | R | правая сторона текста | | l | Л | левая сторона текста | | i | I | внутренний край — рядом с переплётом (в *twoside* документе) | | или | O | внешний край — далеко от переплёта | Верхний регистр позволяет рисунку «плавать». Нижний регистр означает *точно здесь*. Теперь вы можете определить `wrapfigure` окружение с помощью команд `\begin{wrapfigure}{l}{0.25\textwidth} \end{wrapfigure}`. Обратите внимание, что окружение имеет два дополнительных параметра, заключённых в фигурные скобки. Ниже код объясняется более подробно: **{l}** Это определяет выравнивание рисунка. Установите l для левого выравнивания и r для правого. Кроме того, если вы используете книгу или любой аналогичный формат, вместо этого используйте o для внешнего края и i для внутреннего края страницы. **{0.25\textwidth}** Это ширина рамки рисунка. Это не ширина самого изображения, её нужно задавать в команде \includegraphics. Обратите внимание, что длина задана относительно ширины текста, но можно использовать и обычные единицы (cm, in, mm и т. д.). Список единиц см. в справочном руководстве. **\centering** Это уже было объяснено, но в этом примере изображение будет центрировано с использованием своего контейнера в качестве ориентира, а не всего текста. Более полную статью о размещении изображений см. [Размещение изображений и таблиц](/latex/ru/risunki-i-tablicy/02-positioning-images-and-tables.md) [Откройте пример изображений в Overleaf](https://www.overleaf.com/project/new/template/19397?id=65443742\&templateName=Inserting+Images\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## Подписи, метки и перекрёстные ссылки Добавление краткого описания к изображениям и назначение им меток для дальнейших ссылок — два важных инструмента при работе с большим текстом. ### Подписи Начнём с примера подписи: ```latex \begin{figure}[h] \caption{Пример параметрического графика ($\sin (x), \cos(x), x$)} \centering \includegraphics[width=0.5\textwidth]{spiral} \end{figure} ``` ![Пример параметрического графика](/files/68ef131db5435042f8f2a37d5ac50f593fd573a2) Это очень просто, просто добавьте `\caption{Некоторая подпись}` и внутри фигурных скобок напишите текст, который нужно показать. Расположение подписи зависит от того, где вы разместите команду; если она находится выше `\includegraphics` то подпись будет над ним, если ниже, то подпись также будет расположена под рисунком. Подписи также можно размещать сразу после рисунков. Пакет `sidecap` использует похожий код на тот, что в предыдущем примере, чтобы это сделать. ```latex \documentclass{article} \usepackage[rightcaption]{sidecap} \usepackage{graphicx} %пакет для работы с изображениями \graphicspath{ {images/} } \begin{SCfigure}[0.5][h] \caption{Снова использование изображения вселенной. Эта подпись будет справа} \includegraphics[width=0.6\textwidth]{universe} \end{SCfigure} ``` ![Пример параметрического графика с подписью](/files/09c89c68a69bb414beec0237facdc6ed61c5f208) Есть две новые команды **\usepackage\[rightcaption]{sidecap}** Как и следовало ожидать, эта строка импортирует пакет с именем sidecap, но есть дополнительный параметр: rightcaption. Этот параметр задаёт размещение подписи справа от изображения, также можно использовать leftcaption. В документах, похожих на книги, доступны также outercaption и innercaption. Названия говорят сами за себя. **\begin{SCfigure}\[0.5]\[h] \end{SCfigure}** Определяет окружение, похожее на figure. Первый параметр — это ширина подписи относительно размера изображения, как указано в \includegraphics. Второй параметр h работает точно так же, как в окружении figure. См. раздел о размещении для получения дополнительной информации. Вы можете выполнять более продвинутое управление форматированием подписи. См. [разделе дополнительного чтения](#further-reading) раздел для ссылок. ### Метки и перекрёстные ссылки На рисунки, как и на многие другие элементы в документе LaTeX (формулы, таблицы, графики и т. д.), можно ссылаться внутри текста. Это очень просто: просто добавьте `\label` к `figure` или `SCfigure` окружению, а затем позже используйте эту метку, чтобы ссылаться на рисунок. ```latex \begin{figure}[h] \centering \includegraphics[width=0.25\textwidth]{mesh} \caption{хороший график} \label{fig:mesh1} \end{figure} Как вы можете видеть на рисунке \ref{fig:mesh1}, функция возрастает около 0. Также на странице \pageref{fig:mesh1} тот же пример. ``` ![Пример рисунка с меткой](/files/7564c513f67edad9caefabead84ae2e18fd1fc25) В этом примере есть три команды, генерирующие перекрёстные ссылки. **\label{fig:mesh1}** Это задаст метку для этого рисунка. Поскольку метки можно использовать для нескольких типов элементов в документе, хорошей практикой является использование префикса, такого как fig: в примере. **\ref{fig:mesh1}** Эта команда вставит номер, присвоенный рисунку. Он генерируется автоматически и будет обновлён, если перед ним вставить другой рисунок. **\pageref{fig:mesh1}** Здесь выводится номер страницы, на которой появляется указанное изображение. Это `\caption` обязательно для ссылки на рисунок. Ещё одна замечательная особенность документа LaTeX — возможность автоматически создавать *список рисунков*. Это просто. ```latex \listoffigures ``` ![Пример списка рисунков](/files/734c7086a940154ba35e7eb84201472664fdc590) Эта команда работает только с рисунками, содержащими подписи, поскольку она использует подпись в таблице. В примере выше перечислены изображения из этой статьи. Важное примечание: при использовании перекрёстных ссылок ваш проект LaTeX должен быть скомпилирован дважды, иначе ссылки, ссылки на страницы и таблица рисунков не будут работать — Overleaf делает это за вас. ## Создание изображений высокого и низкого разрешения До сих пор при указании имени файла изображения в `\includegraphics` команде мы опускали расширения файлов. Однако это не обязательно, хотя часто полезно. Если расширение файла не указано, LaTeX будет искать любой поддерживаемый формат изображения в этом каталоге и будет искать различные расширения в порядке по умолчанию (который можно изменить). Это полезно при переключении между средами разработки и производства. В среде разработки (когда статья/отчёт/книга ещё в процессе подготовки) желательно использовать изображения низкого разрешения (обычно в формате .png) для быстрой компиляции предварительного просмотра. В производственной среде (когда создаётся финальная версия статьи/отчёта/книги) желательно включать изображения высокого разрешения. Это достигается путём * Не указывать расширение файла в *\includegraphics* команде и * Указать нужное расширение в преамбуле. Таким образом, если у нас есть две версии изображения, venndiagram.pdf (высокого разрешения) и venndiagram.png (низкого разрешения), мы можем включить следующую строку в преамбулу, чтобы использовать версию .png при разработке отчёта — ```latex \DeclareGraphicsExtensions{.png,.pdf} ``` Приведённая выше команда гарантирует, что если встретятся два файла с одинаковым базовым именем, но разными расширениями (например, venndiagram.pdf и venndiagram.png), то сначала будет использоваться версия .png, а при её отсутствии — версия .pdf; это также хорошая идея, если какие-то низкоразрешённые версии недоступны. После того как отчёт будет подготовлен, чтобы использовать высокоразрешённую версию .pdf, мы можем изменить строку в преамбуле, задающую порядок поиска расширений, на ```latex \DeclareGraphicsExtensions{.pdf,.png} ``` Улучшая технику, описанную в предыдущих абзацах, мы также можем указать LaTeX генерировать версии изображений .png низкого разрешения «на лету» при компиляции документа, если есть PDF, который ещё не был преобразован в PNG. Для этого мы можем добавить следующее в преамбулу после `\usepackage{graphicx}` ```latex \usepackage{epstopdf} \epstopdfDeclareGraphicsRule{.pdf}{png}{.png}{convert #1 \OutputFile} \DeclareGraphicsExtensions{.png,.pdf} ``` Если существует venndiagram2.pdf, но не venndiagram2.png, будет создан и загружен вместо него файл venndiagram2-pdf-converted-to.png. Команда *convert #1* отвечает за преобразование, и между *convert* и *#1*могут передаваться дополнительные параметры. Например — *convert -density 100 #1*. Однако есть несколько важных моментов, о которых следует помнить: * Чтобы автоматическое преобразование работало, нам нужно вызвать *pdflatex* с `--shell-escape` параметр. * Для финальной *производственной* версии мы должны закомментировать `\epstopdfDeclareGraphicsRule`, чтобы загружались только PDF-файлы высокого разрешения. Нам также нужно будет изменить порядок приоритета. [Откройте пример изображений в Overleaf](https://www.overleaf.com/project/new/template/19397?id=65443742\&templateName=Inserting+Images\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## справочнике **Единицы и длины LaTeX** | Сокращение | Определение | | ------------ | --------------------------------------------------- | | pt | Пункт — единица длины по умолчанию. Около 0.3515 мм | | мм | миллиметр | | см | сантиметр | | в | дюйм | | ex | высота **x** в текущем шрифте | | em | ширина **m** в текущем шрифте | | \columnsep | расстояние между колонками | | \columnwidth | ширина колонки | | \linewidth | ширина строки в текущем окружении | | \paperwidth | ширина страницы | | \paperheight | высота страницы | | \textwidth | ширина текста | | \textheight | высота текста | | \unitlength | единиц длины в *picture* окружение. | **Об типах изображений в LaTeX** **latex** При компиляции с latex мы можем использовать только изображения EPS, которые являются векторным форматом. **pdflatex** Если мы компилируем с помощью "pdflatex" для получения PDF, тогда мы можем использовать ряд форматов изображений — ``` JPG: лучший выбор, если мы хотим вставить фотографии PNG: лучший выбор, если мы хотим вставить диаграммы (если не удалось сгенерировать векторную версию) и снимки экрана PDF: хотя мы привыкли видеть PDF-документы, PDF также может хранить изображения EPS: изображения EPS можно включать с помощью пакета epstopdf (нам просто нужно установить пакет, нам не нужно использовать \usepackage{}, чтобы включить его в наш документ.) ``` **Векторный формат или растровый формат?** Изображения могут быть либо векторного формата, либо растрового. Обычно нам не нужно об этом беспокоиться, но если мы знаем формат изображения, мы можем использовать эту информацию, чтобы выбрать подходящий формат изображения для включения в наш документ LaTeX. Если у нас есть изображение в векторном формате, следует выбрать PDF или EPS. Если оно в растровом формате, следует выбрать JPG или PNG, поскольку хранение растровых изображений в PDF или EPS занимает много места на диске. [Откройте пример изображений в Overleaf](https://www.overleaf.com/project/new/template/19397?id=65443742\&templateName=Inserting+Images\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## Дополнительное чтение Для получения дополнительной информации см. * [Размещение изображений и таблиц](/latex/ru/risunki-i-tablicy/02-positioning-images-and-tables.md) * [Списки таблиц и рисунков](/latex/ru/risunki-i-tablicy/03-lists-of-tables-and-figures.md) * [Односторонние и двусторонние документы](/latex/ru/formatirovanie/08-single-sided-and-double-sided-documents.md) * [Длины в LaTeX](/latex/ru/formatirovanie/01-lengths-in-latex.md) * [**floatrow** пакет для расширенного управления подписями плавающих элементов (таблиц и рисунков)](http://tug.ctan.org/tex-archive/macros/latex/contrib/floatrow/floatrow.pdf) * [**sidecap** документация к пакету, для подписей к боковым рисункам](ftp://ctan.tug.org/tex-archive/macros/latex/contrib/sidecap/sidecap.pdf) * [**epstopdf** документация к пакету (преобразование EPS в PDF)](https://ctan.org/pkg/epstopdf?lang=en) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/latex/ru/drugie-temy/27-inserting-images.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.