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

Ссылки — это ключевой компонент любой вики не только среди множества документов, но и в пределах одного. К счастью, ссылки очень легко создавать, даже несмотря на то, что есть очень много способов сделать их!

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

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

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

Ссылка (Link Type)

Это тип создаваемой вами ссылки. Тип по умолчанию, URL, используется в сети — или в MDN, или вне его. Вы также можете выбрать "Link to anchor in the text" или "Email". Ссылка-якорь позволяет вам привязать её к якорю, созданному вами ранее с помощью кнопки Вставить / редактировать якорь  на панели инструментов. Опция email позволяет вам настроить: URL-адрес получателя, получателя и сообщение. Чаще всего вы будете использовать тип URL.

Поиск ссылки по заголовку / Текст ссылки (Article Title Lookup / Link Text)

У этого поля есть две цели: во-первых, вы обозначаете текст, который будет использован как указатель ссылки (или, если вы выделили текст до открытия окна, он будет отображён как указатель ссылки), во-вторых, текст, введённый в это поле, используется для поиска  статей на MDN, чтобы найти возможное направление ссылки. К примеру, если вы введёте "Array" в поле, вы увидите что-то наподобие этого:

На картинке вы можете видеть все страницы MDN, чьи заголовки содержат текст, напечатанный вами. Вы можете прокрутить список и выбрать одну из страниц или продолжить набирать текст, сужая список. Заметьте, у названий страниц отображается их язык (в нашем примере это "[en-US]"). Это не отображается в указателе ссылки; так сделано для того, чтобы вы убедились, что вы ссылаетесь на статью того же языка, на котором пишете вы.

Прикрепление ссылки (Attachments)

В качестве альтернативы вы можете сделать так, чтобы ссылка была привязана к одному из файлов, прикреплённому к этой странице. Это отличный способ предоставить ссылку для скачивания примера кода и тому подобное.

URL

Наконец, поле для URL-адреса позволяет вам ввести URL; в поле также выводятся URL выбранных вами элементов из меню Article Title Lookup или Attachments, если вы их использовали. Нередко используют URL-адреса страниц MDN, поэтому, если вы ссылаетесь на другую страницу MDN, удалите доменное имя ("https://developer.mozilla.org") из начала URL.

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

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

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

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

На примере: подсказки — это возможные совпадения. Кажется, 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.

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

HTMLElement

Вставляет в HTML-код название элемента с необходимыми стилизацией и ссылками. К примеру: {{HTMLElement("table")}} даёт <table> (en-US).

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")}}. По умолчанию текст ссылки — это название области, но вы можете добавить второй, необязательный, параметр, обозначающий альтернативный текст. Несколько примеров:

• {{anch("Использование панели инструментов")}} будет выглядеть так: Использование панели инструментов
• {{anch("Использование панели инструментов", "Ранее в этой статье")}} выведет: Ранее в этой статье

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

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

WebKit (Safari и т.д.)

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

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

Ссылки к информации о 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 preference и для того, чтобы привязать её к соответствующей странице в Preference reference, используйте макрос pref . У него всего один параметр: полное название привилегерованного элемента. Например, {{pref("javascript.options.showInConsole")}} преобразуется в: javascript.options.showInConsole.

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

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

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

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

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

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