github flavored markdown to html
1.0.0
Удобный пользовательский фронт питона и командного фронта для преобразования разметки в HTML. Он использует GitHubs Online Markdown-HTML-API по умолчанию (который требует интернет-подключения), но поставляется с опцией для офлайн-преобразования (что близко к ним имитирует поведение GitHubs), и любой другой инструмент Python- или Commandline также может быть подключен к нему. То, что вы его используете, автоматически расширяется с помощью множества функциональности, таких как более подробные варианты вывода, CSS со вкусом GitHub, поддержка формулы, расширенное кэширование изображений и оптимизация, готовое к хосту, расположение файлов и изображения, PDF-конверсия, поддержка короткометражного кода смайлика, поддержка TOC и многое другое.
Хотя его основная цель-создание статических страниц из файлов Markdown, например, в сочетании со статичным веб-сайтом или действиями GitHub, если вы размещаете на GitHub, он может быть очень хорошо используется для любых других целей.
Вот (не обязательно обширный) список его преимуществ и функций:
$ -formula- $ , чтобы использовать их), чего обычно не делает GitHub. GH-MD-TO-HTML использует латекс и DVISVGM, если они оба установлены (преимущество: быстро, не требует интернета), и в противном случае Codecogs Ecdeditor (преимущество: не требует, чтобы вы устанавливали 3 ГБ библиотеки латекса) для достижения этого.[[_TOC_]] , {:toc} и [toc] в начале пустой линии в остальном, чтобы создать таблицу контента для документа, такую как Gitlab-со вкусом отметки, среди прочего.Если вы ищете альтернативу Pandoc для преобразования разметки в PDF, вот список причин, по которым вы можете использовать GH-MD-HTML вместо Pandoc для работы:
В то время как использование Pandoc для преобразования из Markdown в PDF обычно дает более красивые результаты (в конце концов, Pandoc использует LaTex), GH-MD-TO-HTML имеет свой собственный набор преимуществ, когда речь идет о быстрое преобразование сложных файлов для домашнего задания или других целей, где надежность весит больше, чем красота:
$ -signs и каких символов, с которой может начаться формула. Эти правила не применяются в некоторых общих редакторах отметки, таких как MarkText, что приводит к большому разочарованию, когда формулы, которые работали в редакторе, больше не работают при преобразовании с Pandoc (собственная экспорта-функция MarkText-To-PDF иногда не удается в файлах, страдающих формулами без сообщения об ошибке, что делает его еще менее надежной). Хуже всего то, что всякий раз, когда Pandoc не удается преобразование .md в .pdf из-за этого, он показывает номер строки ошибки на основе промежуточного .tex-файла вместо входного .md-файла, что затрудняет поиск корня проблемы. Как вы уже догадались, GH-MD-HTML не мог меньше наплевать на количество пробелов, с которым вы начинаете свои формулы, оставляя это решение для вас.Подводя итог, это подвести итог, что конверсия PANDOC действует довольно необычно, когда дело доходит до изображений, вложенные списки, многослойные записи пулей или формулы, а GH-MD-TO-HTML-нет.
Используйте pip3 install gh-md-to-html чтобы установить непосредственно из индекса пакета Python или python3 -m pip install gh-md-to-html если вы находитесь в Windows.
Оба могут потребоваться sudo на Linux, и вы можете при желании сделать
python3 -m pip install gh-md-to-html[pdf_export]
и установить wkhtmltopdf (v0.12.6 или более), чтобы получить дополнительную функцию PDF-конверсии и преобразовать файлы разметки в PDF и/или
python3 -m pip install gh-md-to-html[offline_conversion]
Чтобы получить дополнительную функцию автономной конверсии и запуск.
Если вы находитесь в Windows , вам, возможно, придется добавить wkhtmltopdf в свой путь в свой текущий рабочий каталог, чтобы перенести преобразование PDF в работу, например, с PATH=%PATH%;c:/program files/wkhtmltopdf/bin или что -то подобное, в зависимости от места вашей установки.
Если вы хотите получить доступ к интерфейсу со своей командной строкой, вы можете просто подать gh-md-to-html с аргументами, задокументированными в тексту справки (доступный с gh-md-to-html -h и показан ниже). В Windows вы должны предоставить python3 -m gh_md_to_html с соответствующими аргументами.
Если вы хотите получить доступ к интерфейсу через Python, вы можете использовать
import gh_md_to_html а затем используйте gh_md_to_html.main() с теми же аргументами (и значениями по умолчанию), которые вы отправите в интерфейс командной строки.
Если вы хотите только подражать результатам конверсии доходностью по API GitHub Resi, но не хотите кэширования изображений, поддержки формулы и модного стиля CSS, используйте, используйте
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
в Python.
Использование : gh-md-to-html <input_name> <optional_arguments>
Поведение по умолчанию :
По умолчанию GH-MD-TO-HTML принимает имя файла разметки в качестве аргумента и сохраняет сгенерированный HTML в файле с тем же именем, с .html вместо .md .
Некоторые причуды:
github-markdown-css/github-css.css (добавить -c , чтобы сделать его встроенными)../images (добавить -i , чтобы отключить это).-w если вы хотите напрямую просматривать его в браузере).id и файловые ссылки предназначены для user-content- , так что вы можете внедрить сгенерированный HTML на более крупный веб-сайт, не рискуя столкновениями с удостоверением личности. Некоторые общие варианты использования :
Благодаря прошлым вопросам я понял, что есть некоторые очень общие случаи использования, которые, по -видимому, у большинства людей есть для этого модуля. Вот наиболее распространенные, и какие варианты и аргументы использовать для них:
-i -w --math false --box-width 25cm , хотя GRIP может быть более эффективным для этой цели.--toc , чтобы поддержать синтаксис Gitlab TOC.--math true --emoji-support 0 --dont-make-images-links true .-i -c чтобы иметь все в одном файле. Преобразование файлов Markdown из Интернета с помощью --origin-type :
Возможно, вы захотите не только преобразовать локальный файл разметки, но и файл из репозитория GitHub, веб-построенный или содержимое строки. Просто загружать их или хранить их в файле часто недостаточно, поскольку их местоположение в Интернете также влияет на то, как должны быть разрешены ссылки на изображения, которые они ссылаются. К счастью, GH-MD-TO-HTML получил вашу спину!
Существует ряд различных аргументов, которые вы можете использовать для описания того, какой файл ввода ввода дали ссылки:
--origin-type file : по умолчанию; берет (относительный или абсолютный) путь файла--origin-type repo : принимает PTH в файл разметки в репозитории GitHub, в формате <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md <franch-name>/<path_to_markdown> .md.--origin-type web : принимает URL-адрес файла разметки, размещенного в Интернете.--origin-type string : принимает строку, содержащую уценку. Некоторые из этих вариантов, которые вы используете, влияет на то, как разрешаются ссылки изображений в файле разметки; В более позднем разделе этого чтения подробно описывается это. Точная настраиваемая то, куда идет :
GH-MD-TO-HTML написан с целью создания готового к хозяину статическому веб-сайту с вашим текущим рабочим каталогом в качестве корня. Помимо использования -w , чтобы отключить это и позволить вам просматривать сгенерированный файл непосредственно в браузере, существует ряд вариантов, которые позволяют вам точно настроить то, что происходит, и наиболее широко изменять корень веб -сайта. Нет необходимости делать это, если вы не хотите по какой -то причине, поэтому не пытайтесь читать это, если вам не нужно!
--website-root (или -w ): оставляя эту опцию пустой, как обсуждалось выше, позволяет вам предварительно просмотреть сгенерированный HTML-файл непосредственно в браузере (в большинстве систем, дважды щелкнув его), если вы не хотите размещать сгенерированный HTML-файл, но вы также можете предоставить любой каталог, который вы хотите использовать в качестве корня веб-сайта для этого. По умолчанию по умолчанию ваш текущий рабочий каталог.--destination (или -d ): путь, по сравнению с --website-root , в котором хранится сгенерированный HTML-файл. По умолчанию корень веб -сайта используется для этого.--image-paths (или -i ): Вы можете оставить это пустым, чтобы отключить кэширование изображения, как описано выше (хотя это не будет работать в случае изменения --origin-type ), или предоставить путь относительно корня веб-сайта, чтобы изменить, где хранятся изображения. По умолчанию images .image-paths Directory не автоматически не претендует между несколькими прогонами GH-MD-TO-HTML, чтобы гарантировать, что эта оптимизация может использоваться поперечным при преобразовании нескольких файлов в объеме.--css-paths (или -c ): Вы можете оставить это пустым, чтобы отключить хранение CSS в внешнем файле CSS (полезно, например, если вы хотите преобразовать только один файл), как описано выше, или предоставить путь относительно корреации веб-сайта, чтобы изменить, где будет сохранен файл CSS (называемый github-css.css ). По умолчанию- github-markdown-css .--output-name (или -n ): имя файла, под которым можно сохранить сгенерированный файл HTML в направлении назначения. Вы можете использовать <name> в любой точке этой строки, и она будет автоматически заменена именем файла Markdown, так что, например, gh-md-to-html inp.md -n "<name>-conv.html" будет хранить результат в ino-conv.html (это не работает со --origin-type string , конечно).-n print , чтобы просто написать вывод в STDOUT (распечатать его на консоли) вместо того, чтобы сохранить его где угодно. Значение по умолчанию - <name>.html , поэтому оно адаптируется к имени вашего ввода.--output-pdf (или -p ): файл для хранения сгенерированного PDF. Вы также можете использовать <name> -syntax здесь. Если -p -option не используется, не будет сгенерировано PDF (и вам нужно следовать инструкциям по установке PDFKIT & WKHTMLTOPDF, чтобы работать выше, чтобы эта опция работала), но вы можете использовать -p без каких -либо аргументов, чтобы он использовал <name>.pdf в качестве чувствительного файла по умолчанию по умолчанию. Экспорт как PDF :
Как упомянуто выше, вы можете экспортировать сгенерированный HTML -файл в качестве PDF, используя --output-pdf -Option. Это требует, чтобы вы установили wkhtmltopdf (версия с QT), чтобы добавить его в путь (если вы находитесь в Windows), и для установки pdfkit (например, через pip3 install gh-md-to-html[offline_conversion] ), но все эти требования уже изложены выше в разделе установки.
Однако здесь стоит отметить. Прежде всего, не используйте эту опцию, если у вас есть ценная информация в файле с именем {yourpdfexportdestination}.html , где {yourpdfexportdestination} -это то, что вы предоставили -p , поскольку этот файл будет временно переписан в процессе; Кроме того, не используйте -p вообще, если вы поставляете ненадежный вход в -x -Option.
Есть также некоторые варианты, специально предназначенные для использования с -p ; В настоящее время это:
--style-pdf (или -s ): установите это на false , чтобы отключить стиль сгенерированного файла PDF с помощью CSS GitHub. Возможно, вы захотите сделать это, потому что граница, которую рисует CSS GitHub вокруг страницы, может выглядеть нелогично в PDF -файлах, хотя это также может негативно повлиять на внешний вид других частей, поэтому используйте это с зерном соли. Изменение того, какое преобразователь MARCHDONGE для использования :
GH-MD-TO-HTML на самом деле не делает сама по себе так сильно, когда речь заходит о размещении отметки и преобразовании его в PDF; Вместо этого он оборачивается вокруг так называемого «основного преобразователя», который делает базовое преобразование в соответствии с спецификацией Markdown, и создает свои собственные параметры, функции, настройки и стиль. По умолчанию для этого используется API REST GitHub Markdown, поскольку он ближе всего к тому, что GitHub делает со своими чтениями, но вы также можете придать GH-MD-HTML любой другой базовый преобразователь разметки для работы.
GH-MD-TO-HTML также поставляется с двумя встроенными альтернативными преобразователями ядра для использования, которые подражают API REST GitHub как можно ближе, в то же время добавляя к нему свой собственный индивидуальный подход.
Возможность определить конвертер Core:
--core-converter (или -o ): Вы можете использовать эту опцию для выбора ряда предварительно определенных преобразователей ядра (см. Ниже), если вы хотите отличаться от по умолчанию.
Вы также можете подать команду Bash (в системах Unix/Linux) или команду CMD.Exe в Windows, в которой {md} стоит в качестве заполнителя для того, где нанесен входной установки Shell, будет вставлен GH-MD-HTML. Например,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
будет использовать Pandoc в качестве основного преобразователя.
Вы также можете сделать это, используя несколько команд, например
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
Пока результат напечатан в Stdout.
Если вы используете Python-Interface в GH-MD-TO-HTML, вы также можете предоставить любую функцию, которая преобразует строку Markdown в строку HTML в этот аргумент.
Предварительно определенные преобразователи ядра, которые вы можете легко поставить --core-converter в качестве строк:
OFFLINE : подражать API REST Github Rest, но в автономном режиме с использованием Mistune. Это требует, чтобы дополнительные зависимости для «offline_conversion» будут удовлетворены, используя pip3 install gh-md-to-html[offline_conversion] или pip3 install mistune>=2.0.0rc1 .OFFLINE+ : ведет себя идентично в автономном режиме, но он не удаляет потенциально вредный контент, как JavaScript и CSS, как обычно делает API REST GitHub. Не используйте эту функцию, если вам не нужен способ преобразовать безопасные файлы маркировки вручную, не имея всего вашего встроенного JS/стиля! Поддержка встроенных форм :
gh-md-to-html поддерживает по умолчанию встроенные формулы (независимо от того, какой конвертер ядра, см. Выше, вы используете). Это означает, что вы можете написать формулу латекса между двумя табличками доллара на одной линии, и она будет заменена изображением SVG, отображающего указанную формулу. Например,
$e = m cdot c^2$
добавит знаменитую формулу Эйнштейна в качестве изображения SVG, хорошо приостановленного с остальной частью текста, окружающего его, в ваш документ.
gh-md-to-html всегда пытается использовать вашу локальную установку LaTex для выполнения этого преобразования (преимущество: быстро и не требует Интернета). Однако, если латекс или DVISVGM не установлены или не могут их найти, он использует онлайн -конвертер (преимущество: не требует, чтобы вы устанавливали 3 ГБ библиотеки латекса) для достижения этого.
Вы можете использовать следующие параметры для изменения этого поведения:
--math (или -m ): установите это на false , чтобы отключить рендеринг формулы.--suppress-online-fallbacks : Установите это в true , чтобы отключить онлайн-запасной запас для рендеринга формулы, что вынести ошибку, если его требования не установлены локально или не могут быть найдены по какой-то причине. Кэширование изображения и сжатие изображений :
Как объяснено углубленное выше, GH-MD-TO-HTML сохраняет изображения, чтобы все они могли быть загружены из одной и той же папки. Это связано с преимуществами
В дополнение к этим преимуществам, GH-MD-TO-HTML также позволяет устанавливать уровень сжатия изображений для использования для этих изображений. Если вы решите сделать это, каждое изображение будет преобразовано в JPEG (используя фоновый цвет и настройки качества вашего вкуса), а изображения будут понижены, если сгенерированные HTML утверждают, что они не понадобятся в их полноразмерном размере (вы можете использовать это, например, с использованием <img> -tags напрямую в вашем документе и снабжая их из -за width или height значения).
GH-MD-TO-HTML также является единственным преобразователем разметки, способным использовать HTML srcset -Attribute, который позволяет сгенерированному документу ссылаться на несколько по-разному масштабируемые версии того же изображения, из которых браузер будет загружать наименьшие большие из них на меньшие размеры экрана, что приводит к большим уменьшению нагрузки, например, на мобильном телефоне. Включение этой функции может привести к дальнейшему сокращению времени загрузки, не жертвуя каким-либо видимым качеством изображения, что делает GH-MD-TO-HTML лучшим выбором, если вы хотите генерировать быстро загружающие веб-сайты из ваших файлов с высоким изображением.
Возможность использовать для всего этого
--compress-images .
и он принимает часть данных JSON со следующими атрибутами:
bg-color : цвет для использования в качестве цвета фона при преобразовании RGBA-изображений в JPEG (формат RGB). По умолчанию « white » и принимает практически любую цветовую стоимость HTML5 (" #FFFFFF ", " #ffffff ", " white " и " rgb(255, 255, 255) " все были бы допустимыми значениями).progressive : Сохранить изображения как прогрессивные JPEGS. По умолчанию ложь.srcset : Сохраните по -разному масштабированные версии изображения и предоставьте их изображению в его атрибуте SRCSET. По умолчанию ложно. Берет массив различной ширины или True , которая служит ярлыком для « [500, 800, 1200, 1500, 1800, 2000] ».quality : значение от 0 до 100, описывающее, при каком качество, изображения должны быть сохранены. По умолчанию до 90. Если определенный размер указан для определенного изображения в HTML, изображение всегда преобразуется в правильный размер перед снижением качества.Если этот аргумент остается пустым, сжатие вообще не используется. Если этот аргумент установлен на TRUE, все значения по умолчанию используются. Если он установлен на данные JSON, и некоторые значения опущены, для них используются дефолты.
Вы также можете передать DICT вместо строки, содержащей данные JSON, если вы используете эту опцию в Python Frontend.
Сжатие изображений не будет работать по понятным причинам, если вы используете -i для отключения кэширования изображения.
Мой личный выбор :
Маркдаун и отметка, со вкусом GitHub, в целом делают некоторые непопулярные варианты, а GH-MD-TO-HTML, подражая его, также делает много из них. Если ваша цель не должна быть максимально близка, чтобы (со вкусом GitHub), и вы хотите использовать полную мощность, которую предлагает GH-MD-HTML в полной мере, я рекомендую следующий (очень самоуверенный) список настроек и опций. Обратите внимание, что некоторые из них небезопасны при преобразовании пользовательского контента.
--math true : Это уже включено по умолчанию, так что не на самом деле рекомендация, но вы, скорее всего, захотите получить поддержку по математике латекса в вашем файле.--core-converter OFFLINE+ : Это преобразует файлы разметки в автономном режиме вместо использования API REST GitHub, и позволяет использовать небезопасные вещи, такие как встроенный код и каждый HTML, который вы могли бы пожелать в вашем файле Markdown.--compress-images : Есть много способов определить эти варианты, но это позволяет получить большую оптимизацию на кэшированных изображениях, включая использование HTML srcset -Attribute, который ни один другой преобразователь Markdown в настоящее время поддерживает AFAIK.--box-width 25cm : вы, скорее всего, захотите ограничить ширину коробки, в которой отображается содержимое сгенерированного веб-сайта по причинам читабельности, если вы не планируете внедрить сгенерированный HTML в более широкий HTML-файл.--toc true : это позволяет использовать [[_TOC_]] в качестве ярлыка для содержимого в сгенерированном файле.--dont-make-images-links true : По умолчанию GitHub окуняет каждое изображение в ссылку на источник изображения, если изображение уже не завершено в другую ссылку. Эта опция отключает это поведение для большего контроля над ссылками вашего изображения.--emoji-support 2 : GH-MD-TO-HTML поддерживает с использованием шорткодов смайликов, например :joy: которые затем заменяются смайликами в сгенерированном HTML-файле. --emoji-support 2 делает еще один уровень дальше, позволяя вам использовать свои собственные смайлики, так :path/to/funny_image.png: добавить в текст funny_image.png как эмодзи размером с эмодзи.--soft-wrap-in-code-boxes true : По умолчанию Github отображает свои многослойные кодовые ящики с горизонтальной половой прокручиванием, если они подвержены риску переполнения. Вместо этого используйте эту опцию, чтобы (IMHO более разумно) в кодовых ящиках. Обратите внимание, что варианты перечислены заказаны по актуальности, и все они имеют разумные значения по умолчанию, поэтому не чувствуйте себя перегруженным тем, сколько их; Вы можете просто прочитать их, пока не найдете то, что вы ищете, и безопасно игнорировать остальное.
Большинство вариантов предназначены для настройки поведения по умолчанию, поэтому ни один из них не является обязательным для большинства вариантов использования.
usage: __main__.py [-h] [-t {file,repo,web,string}]
[-w WEBSITE_ROOT [WEBSITE_ROOT ...]]
[-d DESTINATION [DESTINATION ...]]
[-i [IMAGE_PATHS [IMAGE_PATHS ...]]]
[-c CSS_PATHS [CSS_PATHS ...]]
[-n OUTPUT_NAME [OUTPUT_NAME ...]]
[-p OUTPUT_PDF [OUTPUT_PDF ...]] [-s STYLE_PDF]
[-f FOOTER [FOOTER ...]] [-m MATH]
[-x EXTRA_CSS [EXTRA_CSS ...]]
[-o CORE_CONVERTER [CORE_CONVERTER ...]]
[-e COMPRESS_IMAGES [COMPRESS_IMAGES ...]]
[-b BOX_WIDTH [BOX_WIDTH ...]] [-a TOC]
MD-origin [MD-origin ...]
Convert markdown to HTML using the GitHub API and some additional tweaks with
python.
positional arguments:
MD-origin Where to find the markdown file that should be
converted to html
optional arguments:
-h, --help show this help message and exit
-t {file,repo,web,string}, --origin-type {file,repo,web,string}
In what way the MD-origin-argument describes the origin
of the markdown file to use. Defaults to file. The
options mean:
* file: takes a relative or absolute path to a file
* repo: takes a path to a markdown-file in a github
repository, such as <user_name>/<repo_name>/<branch-
name>/<path_to_markdown>.md
* web: takes an url to a markdown file
* string: takes a string containing the files content
-w WEBSITE_ROOT [WEBSITE_ROOT ...], --website-root WEBSITE_ROOT [WEBSITE_ROOT ...]
Only relevant if you are creating the html for a static
website which you manage using git or something similar.
--website-root is the directory from which you serve
your website (which is needed to correctly generate the
links within the generated html, such as the link
pointing to the css, since they are all root- relative),
and can be a relative as well as an absolute path.
Defaults to the directory you called this script from.
If you intent to view the html file on your laptop
instead of hosting it on a static site, website-root
should be a dot and destination not set. The reason the
generated html files use root-relative links to embed
images is that on many static websites,
https://foo/bar/index.html can be accessed via
https://foo/bar, in which case relative (non-root-
relative) links in index.html will be interpreted as
relative to foo instead of bar, which can cause images
not to load.
-d DESTINATION [DESTINATION ...], --destination DESTINATION [DESTINATION ...]
Where to store the generated html. This path is relative
to --website-root. Defaults to "".
-i [IMAGE_PATHS [IMAGE_PATHS ...]], --image-paths [IMAGE_PATHS [IMAGE_PATHS ...]]
Where to store the images needed or generated for the
html. This path is relative to website-root. Defaults to
the "images"-folder within the destination folder. Leave
this option empty to completely disable image
caching/downloading and leave all image links
unmodified.
-c CSS_PATHS [CSS_PATHS ...], --css-paths CSS_PATHS [CSS_PATHS ...]
Where to store the css needed for the html (as a path
relative to the website root). Defaults to the
"<WEBSITE_ROOT>/github-markdown-css"-folder.
-n OUTPUT_NAME [OUTPUT_NAME ...], --output-name OUTPUT_NAME [OUTPUT_NAME ...]
What the generated html file should be called like. Use
<name> within the value to refer to the name of the
markdown file that is being converted (if you don't use
"-t string"). You can use '-n print' to print the file
(if using the command line interface) or return it (if
using the python module), both without saving it.
Default is '<name>.html'.
-p OUTPUT_PDF [OUTPUT_PDF ...], --output-pdf OUTPUT_PDF [OUTPUT_PDF ...]
If set, the file will also be saved as a pdf file in the
same directory as the html file, using pdfkit, a python
library which will also need to be installed for this to
work. You may use the <name> variable in this value like
you did in --output-name. Do not use this with the -c
option if the input of the -c option is not trusted;
execution of malicious code might be the consequence
otherwise!!
-s STYLE_PDF, --style-pdf STYLE_PDF
If set to false, the generated pdf (only relevant if you
use --output-pdf) will not be styled using github's css.
-f FOOTER [FOOTER ...], --footer FOOTER [FOOTER ...]
An optional piece of html which will be included as a
footer where the 'hosted with <3 by github'-footer in a
gist usually is. Defaults to None, meaning that the
section usually containing said footer will be omitted
altogether.
-m MATH, --math MATH If set to True, which is the default, LaTeX-formulas
using $formula$-notation will be rendered.
-x EXTRA_CSS [EXTRA_CSS ...], --extra-css EXTRA_CSS [EXTRA_CSS ...]
A path to a file containing additional css to embed into
the final html, as an absolute path or relative to the
working directory. This file should contain css between
two <style>-tags, so it is actually a html file, and can
contain javascript as well. It's worth mentioning and
might be useful for your css/js that every element of
the generated html is a child element of an element with
id xxx, where xxx is "article-" plus the filename
(without extension) of:
* output- name, if output-name is not "print" and not
the default value.
* the input markdown file, if output- name is "print",
and the input type is not string. * the file with the
extra-css otherwise. If none of these cases applies, no
id is given.
-o CORE_CONVERTER [CORE_CONVERTER ...], --core-converter CORE_CONVERTER [CORE_CONVERTER ...]
The converter to use to convert the given markdown to
html, before additional modifications such as formula
support and image downloading are applied; this defaults
to using GitHub's REST API and can be
* on Unix/ any system with a cmd: a command containing
the string "{md}", where "{md}" will be replaced with an
escaped version of the markdown file's content, and
which returns the finished html. Please note that
commands for Unix-system won't work on Windows systems,
and vice versa etc.
* when using gh-md-to- html in python: A callable which
converts markdown to html, or a string as described
above.
* OFFLINE as a value to indicate that gh-md-to-html
should imitate the output of their builtin
md-to-html-converter using mistune. This requires the
optional dependencies for "offline_conversion" to be
satisfied, by using `pip3 install
gh-md-to-html[offline_conversion]` or `pip3 install
mistune>=2.0.0rc1`.
* OFFLINE+ behaves identical to OFFLINE, but it doesn't
remove potentially harmful content like javascript and
css like the GitHub REST API usually does. DO NOT USE
THIS FEATURE unless you need a way to convert secure
manually-checked markdown files without having all your
inline js stripped away!
-e COMPRESS_IMAGES [COMPRESS_IMAGES ...], --compress-images COMPRESS_IMAGES [COMPRESS_IMAGES ...]
Reduces load time of the generated html by saving all
images referenced by the given markdown file as jpeg.
This argument takes a piece of json data containing the
following information; if it is not used, no compression
is done:
* bg-color: the color to use as a background color when
converting RGBA-images to jpeg (an RGB-format). Defaults
to "white" and accepts almost any HTML5 color-value
("#FFFFFF", "#ffffff", "white" and "rgb(255, 255, 255)"
would've all been valid values).
* progressive: Save images as progressive jpegs. Default
is False.
* srcset: Save differently scaled versions of the image
and provide them to the image in its srcset attribute.
Defaults to False. Takes an array of different widths or
True, which serves as a shortcut for "[500, 800, 1200,
1500, 1800, 2000]".
* quality: a value from 0 to 100 describing at which
quality the images should be saved (this is done after
they are scaled down, if they are scaled down at all).
Defaults to 90. If a specific size is specified for a
specific image in the html, the image is always
converted to the right size. If this argument is left
empty, no compression is down at all. If this argument
is set to True, all default values are used. If it is
set to json data and values are omitted, the defaults
are also used. If a dict is passed instead of json data
(when using the tool as a python module), the dict is
used as the result of the json data.
-b BOX_WIDTH [BOX_WIDTH ...], --box-width BOX_WIDTH [BOX_WIDTH ...]
The text of the rendered file is always displayed in a
box, like GitHub READMEs and issues are. By default,
this box fills the entire screen (max-width: 100%), but
you can use this option to reduce its max width to be
more readable when hosted stand-alone; the resulting box
is always centered. --box-width accepts the same
arguments the css max-width attribute accepts, e.g. 25cm
or 800px.
-a TOC, --toc TOC Enables the use of `[[_TOC_]]`, `{:toc}` and `[toc]`
at the beginning of an otherwise empty line to create a
table of content for the document. These syntax are
supported by different markdown flavors, the most
prominent probably being GitLab-flavored markdown
(supports `[[_TOC_]]`), and since GitLab displays its
READMEs quite similar to how GitHub does it, this option
was added to improve support for GitLab- flavored
markdown.
Как упомянуто выше, любое изображение, упомянутое в файле Markdown, хранится локально и ссылается с использованием корневых гиперссылок в сгенерированном HTML. Как преобразователь угадывает местоположение изображения, показано в следующей таблице, с типом ImageLink, отмеченным сверху, и тип входной отметки, отмеченной слева:
https:// или http:// | АБС FilePath | религиозный FilePath | Начиная с / (например, /imagedir/image.png ) | Не начинать с / (например, imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | с адреса | АБС FilePath | религиозный FilePath (откуда лежит .md -файл) | - | - |
-t string | с адреса | ABS.FilePath, но нуждается в подтверждении по соображениям безопасности | религиозный FilePath (куда называется инструмент), но нуждается в подтверждении по соображениям безопасности | - | - |
username/repo/dir/file.md -t repo | с адреса | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | с адреса | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
Как и во всех моих проектах, обратная связь (даже если это просто что -то маленькое, например, сказать мне ваш вариант использования для моего проекта или сказать мне, что вам не понравилась структура Readme, или сказать мне, что вам специально понравилась одна конкретная функция), очень ценится и помогает мне сделать этот проект лучше, даже если это что -то очень крошечное! Вы можете просто бросить проблему со своими отзывами, короткой и неформальной или даже написать мне, если вы не хотите поднимать проблему по какой-то причине. В настоящее время я не планирую добавлять функции в будущем, но я всегда открыт для исправления и настройки существующих функций, документации и так далее, и я, очевидно, хотел бы услышать ваши предложения по функциям, даже если я не планирую добавлять их в ближайшем будущем.
Я, как правило, очень отзывчив, когда дело доходит до проблем с GitHub, и я воспринимаю их очень серьезно и пытаюсь решить их как можно скорее. Если вы столкнетесь с ошибками, странным поведением, ошибками установки и тому подобным, используя мой инструмент, не стесняйтесь говорить мне в проблеме, чтобы я мог решить проблему!
Если вы нашли этот инструмент полезным, пожалуйста, подумайте о том, чтобы сняться в главной роли на GitHub, чтобы показать мне свою признательность! Я также был бы признателен, если бы вы рассказали мне о проблемах, с которыми вы столкнулись, даже если вам удалось исправить их в своей собственной копии кода, поэтому я тоже могу исправить их в этом репо.
gh-md-to-html для преобразования MD-PDF (под суть о преобразовании MD-PDF): ссылкаgh-md-to-html в документации другого проекта: ссылкаЗначки были сделаны
.md-file.icon: Freepik от flaticon.com
.md-file.icon: Freepik от flaticon.com
Arrow-Icon: Font Awesom
Github-iCon: значок GitHub на IconsCout
Отказ от ответственности : этот модуль не написан не GitHub и не одобрен GitHub, поддерживаемым GitHub, основанным на GitHub или аффилирован с GitHub. Он использует только публичный API, предоставленный GitHub, а также .CSS-файл, лицензированный GitHub по лицензии MIT.
