Создание ссылок в статьях MDN
Ссылки — это ключевой компонент любой вики не только среди множества документов, но и в пределах одного. К счастью, ссылки очень легко создавать, даже несмотря на то, что есть очень много способов сделать их!
Обратите внимание, что у нас есть особые правила применения ссылок: они описаны в руководстве по оформлению материалов 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.
В верху окна также есть вкладка Advanced. Нет опций, которые мы советуем вам использовать регулярно, по крайней мере, сейчас. Можете быть, в будущем появятся новые стили для ссылок, но мы, вероятно, добавим новую панель инструментов для этих опций.
Ссылки
Если у вас есть текст, который вы хотели бы превратить в ссылку, вы можете слегка упростить процесс. Выделите нужный вам текст, затем откройте окно для работы с ссылками; поле 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.
Ещё проще посетить KumaScript, где есть любой из этих макросов; ко многим макросам есть комментарии вверху, объясняющие, как макрос работает и какие у него переменные.
Ссылка на документацию для API
У нас есть несколько невероятно полезных макросов для создания стилизованных ссылок для 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
Суть работы Интернета изложена в 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:
, которые блокируются большинством браузеров в целях безопасности.