Take the MDN Survey and help us understand what browser vendors can do to make your life better: https://qsurvey.mozilla.com/s3/MDN-browser-compat-survey

Вы на редактируемой версии веб-документации MDN

Посмотреть как пользователь веб-документации MDN: https://developer.mozilla.org/ru/docs/MDN/Contribute/Editor/Ссылки

Создание ссылок в статьях MDN

Обратите внимание, что у нас есть особые правила применения ссылок: они описаны в руководстве по оформлению материалов MDN.

Использование панели инструментов

Самый очевидный способ создать ссылку — нажать на кнопку Вставить/Редактировать ссылку на панели инструментов или нажать сочетание Ctl+K (Command-K для Mac). Кнопка ссылки вглядит так: The link button (as of 2015-12-04). Вы можете добавлять текст к выделенному тексту.

Создание ссылки

После нажатия на кнопку ссылки появится диалоговое окно для работы с ссылками:

Окно для работы с ссылками

Здесь вы можете создать новую ссылку. Параметры окна:

Ссылка (Link Type)
Это тип создаваемой вами ссылки. Тип по умолчанию, URL, используется в сети — или в MDN, или вне его. Вы также можете выбрать "Link to anchor in the text" или "Email". Ссылка-якорь позволяет вам привязать её к якорю, созданному вами ранее с помощью кнопки Вставить / редактировать якорь  на панели инструментов. Опция email позволяет вам настрить: URL-адрес получателя, получателя и сообщение. Чаще всего вы будете использовать тип URL.
Поиск ссылки по заголовку / Текст ссылки (Article Title Lookup / Link Text)
У этого поля есть две цели: во-первых, вы обозначаете текст, который будет использован как указатель ссылки (или, если вы выделили текст до открытия окна, он будет отображён как указатель ссылки), во-вторых, текст, введённый в это поле, используется для поиска  статей на MDN, чтобы найти возможное направление ссылки. К примеру, если вы введёте "Array" в поле, вы увидите что-то наподобие этого:
Screenshot of the Link dialog box, showing a lookup menu for the text "Array"
На картинке вы можете видеть все страницы MDN, чьи заголовки содержат текст, напечатанный вами. Вы можете прокрутить список и выбрать одну из страниц или продолжить набирать текст, сужая список. Заметьте, у названий страниц отображается их язык (в нашем примере это "[en-US]"). Это не отображается в указателе ссылки; так сделано для того, чтобы вы убедились, что вы ссылаетесь на статью того же языка, на котором пишете вы.
Прикрепление ссылки (Attachments)
В качестве альтернативы вы можете сделать так, чтобы ссылка была привязана к одному из файлов, прикрпеплённому к этой странице. Это отличный способ предоставить ссылку для скачивания примера кода и тому подобное.
URL
Наконец, поле для URL-адреса позволяет вам ввести URL; в поле также выводятся URL выбранных вами элементов из меню Article Title Lookup или Attachments, если вы их использовали. Нередко используют URL-адреса страниц MDN, поэтому, если вы ссылаетесь на другую страницу MDN, удалите доменное имя ("https://developer.mozilla.org") из начала URL.

Как только завершите настройку ссылки, нажмите OK.

В верху окна также есть вкладка Advanced. Нет опций, которые мы советуем вам использовать регулярно, по крайней мере, сейчас. Можете быть, в будущем появятся новые стили для ссылок, но мы, вероятно, добавим новую панель инструментов для этих опций.

Ссылки

Если у вас есть текст, который вы хотели бы превратить в ссылку, вы можете слегка упростить процесс. Выделите нужный вам текст, затем откройте окно для работы с сылками; поле Article Title / Lookup Text будет заполнено выделенным текстом. К примеру, есть у нас, скажем, следующий текст:

You may find it useful to use JavaScript arrays when working on this project.

Нам хотелось бы преобразовать arrays в ссылку на файл с соответствующим содержанием. Просто выделите слово и включите окно для работы с ссылками; у вас появится заполненное окно, похожее на изображение выше. Наводя мышь на поле-подсказку, вы можете видеть её относительный путь (его URL относится к developer.mozilla.org), благодаря чему вы можете лучше узнать, где  находится статья и о чём она.

Screenshot of the Link dialog box, showing a lookup menu and a URL tooltip

На примере: подсказки — это возможные совпадения. Кажется, arrays было выбрано удачно; выберем этот вариант. Поле сразу заполняется URL-адресом, поэтому мы просто жмём OK, и цитата будет выглядеть так:

You may find it useful to use JavaScript arrays when working on this project.

Использование макросов

MDN часто использует макросы, чтобы автоматически создавать термины-ссылки с соответствующим содержанием, стилизуя их как ссылки в сответствии с нашими правилами оформления элементов. Учтите: наше руководство отмечает, что API-термины, элементы и атрибуты HTML, свойства, имена функций CSS и тому подобное,— должны быть стилизованы с помощью элемента <code>. Также должны быть ссылки на другие страницы MDN.

К использованию макросов для создания ссылок легко привыкнуть, и это предоставляет множество плюсов:

  • Стили добавлены для вас.
  • Ссылка создана для вас — и она не подвергается изменениям, если структура MDN меняется.
  • Соответствующие подсказки также созданы для вас.

Есть очень много таких макросов, и мы не будем останавливаться на них подробно здесь. Вместо этого мы разберём несколько самых часто употребляемых. Если интересно, ознакомьтесь с разделом "Создание гиперссылок" в нашей статье Пользовательский макрос для MDN.

Ещё проще посетить KumaScript, где есть любой из этих макросов; ко многим макросам есть комментарии вверху, объясняющие, как макрос работает и какие у него переменные.

Ссылка на документацию для API

У нас есть есколько невероятно полезных макросов для создания стилизованных ссылок для API. В этом подразделе перечислены самые удобные; в каждый блок могут быть добавлены доступные параметры, чтобы предоставить больший контроль над выводом. На название каждого макроса можно кликнуть, чтобы увидеть сам код макроса; у каждого макроса есть комментарии вверху, объясняющие, как макрос работает и какие у него переменные.

HTMLElement
Вставляет в HTML-код название элемента с необходимыми стилизацией и ссылками. К примеру: {{HTMLElement("table")}} даёт <table>.
cssxref
Вставляет в CSS-код документацию свойства, правила или селектора. Например: {{cssxref("background-color")}} в результате выводит background-color.
domxref
Вставляет данный термин API. Пример: {{domxref("window")}} даёт в результате window, и {{domxref("window.scrollBy()")}} вставляет window.scrollBy(). Вы также можете вставить дополнительный параметр, чтобы заменить текст: {{domxref("window.scrollBy", "scrollBy()")}} заменяет window.scrollBy на scrollBy().
SVGElement
Вставляет название SVG-элемента с необходимыми стилизацией и ссылками. К примеру: {{SVGElement("circle")}} даёт <circle>.

Добавление якорей

Чтобы применить ссылку к области с таким же названием, следует использовать макрос anch. Синтаксис — проще некуда: {{anch("Name of destination section")}}. По умолчанию текст ссылки — это название области, но вы можете добавить второй, необязательный, параметр, обозначающий альтернативный текст. Несколько примеров:

Ссылки к багам

Вы можете создать ссылку на базу данных Mozilla's Bugzilla с макросом bug. У этого макроса всего один параметр: номер бага, на который ссылаются. К примеру, {{bug(765642)}} покажет: баг 765642.

Таким же образом вы можете создавать ссылки к багам на других брузерах и брузерных движках:

WebKit (Safari и т.д.)
WebkitBug: {{webkitbug(31277)}} даёт Баг WebKit 31277.

Ссылки к RFC

Суть работы Интернета изложена в RFC. Вы можете с лёгкостью обратиться к RFCs с помощью RFC. Для примера, {{RFC(2616)}} станет RFC 2616. Вы можете при желании снабдить макрос альтернативной ссылкой, чтобы использовать вместо выделенного участка текста или нескольких участков, с описанием, к какой ссылке привязать их.

Ссылки к информации о XPCOM-интерфейсах

MDN больше не поддерживает XPCOM-документацию, но внесение вклада приветствуется!

Если вы документируете свойства Mozilla, способность быстро создать ссылку к документации XPCOM очень полезна. Здесь несколько макросов для этого.

Синтаксис: {{interface("interfacename")}}. К примеру, вы написали:

When you need to parse or create URIs, the {{interface("nsIIOService")}} interface can help.

В результате получится

When you need to parse or create URIs, the nsIIOService interface can help.

Если вам нужна ссылка к информации о методе или атрибуте XPCOM-интерфейса, макросы ifmethod и ifattribute точно для вас. Названия интерфейса и метода или атрибута, к которым вы ссылаетесь, принимаются за параметры. Макрос ifmethod особенно интересен, т.к. он по-особому форматирует элемент при добавлении стиля родителя после названия метода. Например, {{ifmethod("nsIIOService", "newURI")}} выводит nsIIOService.newURI(). Это контейнер, в котором вы защищены от стилевых изменений MDN в будущем!

Ссылка к привилегированной документации Mozilla

Для вставки Mozilla preference и для того, чтобы привязать её к соответствующей странице в Preference reference, используйте макрос pref . У него всего один параметр: полное название привилегерованного элемента. Например, {{pref("javascript.options.showInConsole")}} преобразуется в: javascript.options.showInConsole.

Ссылка к ресурсам Mozilla

Вы можете ссылаться на дерево ресурсов Mozilla's (хотя не стоит делать это часто), используя макрос source. Вместо указания абсолютного пути вам достаточно указать путь относительно директории /source/. Для примера: {{source("browser/Makefile.in")}} создаёт эту ссылку: browser/Makefile.in.

Вы можете при желании снабдить ссылку альтернативным тектсом. Например, как видите, {{source("browser/Makefile.in", "the browser's makefile")}} преобразуется в: the browser's makefile.

Обратите внимание на документацию Использование макросов, если вы заинтересованы в более подробном изучении макросов и посетите KumaScript, чтобы больше узнать о системе макросов.

Ссылки на рекомендованные статьи

Если вы хотите создать список связанных страниц или другого рекомендованного материала к прочтению, вам следует делать это с помощью создания контейнера быстрых ссылок в боковой панели. Такой подход заменяет наши старые Смотрите также в конце статей. О том, как создавать контейнер с быстрыми ссылками, читайте в статье Быстрые ссылки.

Схемы URL-адресов

В целях безопасности создавайте ссылки, имеющие следующие схемы:

  • http://
  • https://
  • ftp://
  • mailto:

Дргуие схемы просто-напросто будут удалены.

Особые URL-схемы, такие как about: и chrome: используются Firefox, Google Chrome и некоторыми другими браузерами, чтобы предоставить доступ к особым опциям, таким как привилегерованные элементы, отладочная информация и так далее. Эти ссылки не работают в содержимом статьи, поэтому не создавайте ссылки, используя эти схемы в MDN. То же относится и к схемам javascript: и jar:, которые блокируются большинством браузеров в целях безопасности.

Метки документа и участники

Внесли вклад в эту страницу: Ivan961
Обновлялась последний раз: Ivan961,