Создавайте красивые заметки из файлов Markdown с помощью Gatsby, React и GraphQL, которые поддерживают блоки кода, математические уравнения и многое другое.

Первоначально как личный проект, чтобы почесать царапину, так как мой стартовый шаблон Gatsby был объединен с официальной веткой, я подумал, что было бы продуктивно поделиться ключевыми вещами, которые я узнал при создании простого статического сайта Gatsby для размещения моих заметок и материалов для исправлений. Если вы хотите создать свой сайт для ведения заметок, используя markdown, создайте вилку страницы Github. Если вы хотите узнать больше о Gatsby, React и Markdown, продолжайте!

Зуд

Когда я изучаю информатику, мне нужен инструмент для заметок, чтобы:

  • сделать написание кода простым и беспроблемным, выделение синтаксиса в моих заметках будет большим плюсом
  • поддерживать уравнения в стиле LaTeX, поэтому я могу добавлять математику
  • вставлять изображения для таких вещей, как диаграммы и изображения
  • быть высоко автоматизированным; Я должен быть в состоянии сосредоточиться на содержании, а не на управлении системой, которая делает тяжелую работу

Markdown - это популярный гибкий формат файлов, который поддерживает все эти требования (и многое другое). Конвертеры типа Pandoc отлично подходят для записи в Markdown и преобразования в PDF с помощью латексного конвертера. Проблема с этим подходом заключается в том, что у меня будет просто много файлов, разбросанных повсюду! Файлы, журналы и PDF-файлы Markdown загромождали бы каталоги, и редактирование моих заметок было бы довольно болезненным процессом.

Примерно в этот момент я осознал сходство между моим текущим блогом (работающим на Gatsby) и тем, что мне нужно для ведения заметок. Единственные реальные требования, касающиеся улучшения кода и математической вставки в документ, а также организации файлов уценки.

Гэтсби

Gatsby - это мощный, «невероятно» быстрый генератор статических сайтов. Он позволяет вам писать многократно используемый и часто минимальный объем кода для создания надежного статического сайта, а с помощью множества плагинов вы можете расширить его возможности для выполнения многих полезных задач.

Когда я только начал изучать веб-разработку, идея Гэтсби сбила меня с толку. Что это дает мне? Что не так со святой троицей HTML, CSS и Javascript? Ответ в том, что в этом нет ничего плохого. Gatsby может просто предложить несколько удивительных инструментов для улучшения вашего общего опыта разработки, а также удобства ваших пользователей.

Честно говоря, они больше не рекламируют себя как генератор статических сайтов. Вместо этого они представляют собой генератор статических прогрессивных веб-приложений. Гэтсби похож на менеджера проекта - он знает, как управлять всеми отдельными частями, чтобы добиться максимальной продуктивности и эффективности от каждого и предоставить лучший продукт в конце. Эти люди включают React (интерфейсный фреймворк), Webpack (для всех ваших потребностей в объединении файлов), GraphQL (для упрощения обработки данных) и современный Javascript.

Прежде чем углубиться в подробности, я упомяну в качестве отказа от ответственности, что предполагаю некоторые знания React и GraphQL для этого сообщения в блоге. Позже у меня есть удобный учебник по GraphQL, но если вам нужна дополнительная информация, проверьте эти источники.

Базовая структура проекта Gatsby для создания заметок выглядит примерно так:

|-- /src 
    |-- /components   (All of the React Components)    
    |-- /pages        (All of the Markdown Content)
    |-- /templates    (Layouts for the Content)
|-- package.json      (Node package management data)
|-- gatsby-config.js  (Config - like package.json only for Gatsby)
|-- gatsby-node.js    (Node APIs - createPages, onCreateNode...)
|-- gatsby-browser.js (Browser APIs/external js and css loaded here)

В этой статье мы проведем много времени в папке pages, а также в файлах gatsby-config.js и gatsby-node.js соответственно, поскольку именно здесь происходит вся магия. Чтобы начать работу с простым сайтом Gatsby, возможно, попробуйте установить интерфейс командной строки и запустить gatsby new awesome-site. В противном случае давайте погрузимся.

API узла Gatsby

Узлы в Gatsby - это центральная единица данных. Все данные, добавляемые на ваш сайт, как правило, моделируются с использованием узлов, и у них есть полезные поля-члены, такие как объект parent, fields, которые плагины могут использовать для расширения узла и объекта internal с информацией о типе. Они станут полезными.

Первое, что нам нужно сделать, это получить доступ к файлам в нашем проекте и иметь возможность создавать страницы на их основе. Для меня это похоже на Node API. Чтобы получить доступ к таким полезным функциям, как createPage и onCreateNode, нам нужно добавить gatsby-source-filename в наш проект, используя yarn или npm.

Давайте сначала рассмотрим более простую функцию из того, что мы должны делать при создании нового узла. Наша проблема в том, что нет способа узнать, где должна быть наша новая страница, ей нужно новое свойство поля slug. К сожалению, это относится не к наземному брюхоногому моллюску без панциря, а к уникальному идентификатору в URL, который отличает данную страницу. Но это должно иметь место только для наших файлов Markdown. Полезно знать, когда мы создаем их, узлы будут иметь: node.internal.type = 'MarkdownRemark', поэтому мы можем использовать это, чтобы проверить, что добавляем свойство slug для исправления файлов.

Теперь немного более сложный, но очень важный шаг по созданию наших новых страниц. Для этого мы используем createPage API, а также GraphQL. Если вы новичок в GraphQL (как и я), вот краткое руководство из одного абзаца со ссылками для изучения синтаксиса и важных концепций.

GraphQL Primer

GraphQL - это язык запросов, как следует из названия, с упором на то, чтобы сделать данные легко запрашиваемыми и очень гибкими для человека, отправляющего запрос, возвращающего только те данные, которые вы хотите. Синтаксически он напоминает JSON. И типичный запрос может выглядеть примерно так, взятый с сайта Гэтсби:

// Normal imports into the project
import React from "react"
import { graphql } from "gatsby"
// Simple functional component that consumes the data we get 
export default ({ data }) => (
   <div>
     <h1>About {data.site.siteMetadata.title}</h1>
     <p>We're a very cool website you should return to often.</p>
   </div>
)
// The graphql query to get the site title (from the config file)
export const query = graphql`
   query {
     site {
       siteMetadata {
         title
       }
     }
   }
`

По своей сути GraphQL - это определение полей из объектов. В приведенном выше запросе мы запрашиваем title нашего site, который находится в siteMetadata. Одним из наиболее важных аспектов GraphQL является то, что возвращаемый тип точно такой же, как и тот, который вы указали, что значительно упрощает манипулирование данными и работу с ними. Ниже приведен результат выполнения этого запроса.

{
  "data": {
    "site": {
      "siteMetadata": {
        "title": "Gatsby Notes Starter"
      }
    }
  }
}

Всякий раз, когда мы создаем новую страницу из наших файлов Markdown, нам нужно запрашивать их, чтобы получить данные, необходимые для создания новых страниц. Для этого мы используем плагин gatsby-transformer-remark. Полную информацию о плагине можно найти здесь, но по сути он ищет наши .md файлы и анализирует их. Чтобы получить наши узлы MarkdownRemark и создать новые страницы, мы используем следующее:

Обратите внимание, как теперь мы можем получить доступ к нашему недавно определенному свойству slug в fields. Если вы зашли так далеко, поздравляем! Самые сложные части настройки более или менее выполнены, и теперь нам просто нужно сгенерировать наши заметки.

Шаблон

Наш шаблон заметок будет очень простым и будет использовать <Layout/> компонент, любезно предоставленный Гэтсби. Во-первых, нам нужно определить запрос, который получает данные и передает их нашему функциональному компоненту. Запрос будет введен вместе с текущим просматриваемым $slug. Затем с помощью оператора eq мы получаем конкретные данные markdownremark, которые нужно передать компоненту, который отображает страницу. В нашем компоненте мы просто извлекаем необходимые данные и помещаем их в нужные нам места.

Большой! Теперь мы создаем наши страницы, все, что нам нужно, это простая интерфейсная структура для отображения всех наших страниц в организованном виде. Желательно по теме. Для этого я использовал блестящий react-accessible-accordion от springload. Я также использовал lodash для обработки данных.

Вот и все! Все наши заметки теперь отображаются, и истинная мощь библиотеки подключаемых модулей Gatsby становится очевидной: для включения кода и математики в заметки нам просто нужно добавить следующие подключаемые модули в наш gatsby-config.js файл в подключаемом модуле преобразователя. Не забудьте добавить их с помощью пряжи или нпм.

plugins: [
    `gatsby-remark-prismjs`,
    `gatsby-remark-katex`,
    {
        resolve: `gatsby-remark-images`,
        options: {
            maxWidth: 650,
        },
    },
]

Затем вы можете указать, какие prismjs темы вы хотите в gatsby-browser.js файле, а также получить katex css. Я использовал следующие настройки по умолчанию:

require('prismjs/themes/prism-tomorrow.css');
require('katex/dist/katex.min.css');

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

Если вам интересно посмотреть, как это выглядит, перейдите на демонстрационный сайт, размещенный на Netlify (идеальная хостинговая платформа для любого сайта Gatsby). То, что начиналось как желание почесаться, превратилось в действительно приятный проект, который научил меня многому о Gatsby, React и GraphQL. Не говоря уже о том, что я получил довольно полезный и крутой (если можно так сказать) инструмент для отображения и генерации всех моих заметок из университета. Не стесняйтесь разветвлять проект для собственных идей и заметок.