devii
v0.5.0
Um iniciador de blog de desenvolvedor para 2020.
Next.js
Reagir
TypeScript
Markdown
destaque da sintaxe
SEO
Geração RSS
Se você está feliz e sabe disso, estrela este repo
/md/blogMarkdown.tsx com suporte para destaques de sintaxe no estilo GitHubLeia mais sobre a motivação + design por trás do DEVII em https://colinhacks.com/blog/devii.
Este repo contém o código para https://devii.dev.
Devii.dev serve como documentação e uma demonstração de trabalho de Devi. Depois de clonar/forçar, você pode procurar o código para saber como o DEVII funciona. Então você pode eliminar tudo o que não gosta, personalizar todo o resto e construir suas próprias ferramentas e componentes no topo da fundação, o Devii fornece!
Seu site pessoal é a manifestação on -line de você. Devii realmente não fornece muito fora da caixa. Ele fornece alguns estilos padrão de estilo médio agradáveis para as postagens do seu blog e algumas ferramentas para carregar/renderizar o Markdown. Mas você terá que implementar sua própria página inicial mais ou menos do zero. E esse é o ponto! Não se contente com algum tema. Construa algo que represente você.
Para começar:
git clone [email protected]:yourusername/devii.git my-blog
cd my-blog
yarn
yarn dev . Isso deve iniciar um servidor em http://localhost:3000 . O núcleo deste repo é o próximo.js. Escolhemos o Next.js porque é a maneira mais simples e elegante de gerar uma versão estática de um site baseado em React. A documentação é excelente; Leia primeiro: Next.js Documentation.
Aqui está uma versão abreviada da estrutura do projeto. Certos arquivos de configuração ( next.config.js , next-end.d.ts , .gitignore ) foram removidos por simplicidade.
.
├── README.md
├── public // all static assets (images, css, etc) go here
├── pages // every .tsx component in this dir becomes a page of the final site
| ├── index.tsx // the home page (which has access to the list of all blog posts)
| ├── blog
| ├── [blog].md // a template component that renders the blog posts under `/md/blog`
├── md
| ├── blog
| ├── devii.md // this page!
├── whatever.md // every MD file in this directory becomes a blog post
├── components
| ├── BlogPost.tsx
| ├── Code.tsx
| ├── Footer.tsx
| ├── Header.tsx
| ├── Markdown.tsx
| ├── Meta.tsx
| ├── <various>
├── loader.ts // contains utility functions for loading/parsing Markdown
├── node_modules
├── tsconfig.json
├── package.json
Next.js gera uma nova página da Web para cada arquivo no diretório pages . Se você deseja adicionar uma página sobre o seu blog, basta adicionar about.tsx Inside pages e comece a escrever a página.
Por padrão, o repositório contém apenas duas páginas: uma página inicial ( /pages/index.tsx ) e uma página do blog ( /pages/[blog].md .md).
O arquivo [blog].ts segue a convenção Next.js do uso de colchetes quadrados para indicar uma rota dinâmica.
A página inicial é intencionalmente mínima. Você pode colocar o que quiser em index.tsx ; Um de nossos objetivos ao projetar Devii era não colocar restrições ao desenvolvedor. Use sua imaginação! Seu site é a manifestação on -line de você. Você pode usar quaisquer pacotes NPM ou bibliotecas de estilo que desejar.
Devii é poucopinado sobre o estilo. Como seu site Devii é um aplicativo de reação padrão sob o capô, você pode usar sua biblioteca favorita do npm para fazer estilo.
O DEVII fornece certos estilos por padrão, principalmente no renderizador de marcação ( /components/Markdown.tsx ). Esses estilos são implementados usando a solução de estilo interno do Next styled-jsx . Infelizmente, era necessário tornar esses estilos globais, já que styled-jsx não é bom com componentes de terceiros (neste caso react-markdown ).
Sinta-se à vontade para reimplementar os estilos embutidos com sua biblioteca de escolha se você optar por usar uma biblioteca de estilo separada (a emoção é bastante gloriosa), então você pode implementar os estilos padrão
Basta adicionar um arquivo de marcação em md/blog/ para criar uma nova postagem no blog:
foo.md no diretório /md/bloghttp://localhost:3000/blog/foo . Você deve ver o novo post. Todo arquivo de marcação pode incluir um "bloco frontmatter" contendo vários metadados. O DEVII fornece um utilitário loadPost que carrega um arquivo de marcação, analisa seus metadados frontmatter e retorna um objeto PostData estruturado:
type PostData = {
path : string ;
title ?: string ;
subtitle ?: string ;
description ?: string ; // used for SEO
canonicalUrl ?: string ; // used for SEO
datePublished ?: number ; // Unix timestamp
author ?: string ;
authorPhoto ?: string ;
authorHandle ?: string ; // twitter handle
tags ?: string [ ] ;
bannerPhoto ?: string ;
thumbnailPhoto ?: string ;
} ; Por exemplo, aqui está o blog FrontMatter da postagem de blog de amostra ( md/blog/the-ultimate-tech-stack.md ):
---
title: Introducing Devii
subtitle: Bringing the power of React, TypeScript, and static generation to dev blogs everywhere
datePublished: 1589064522569
author: Ben Bitdiddle
tags:
- Devii
- Blogs
authorPhoto: /img/profile.jpg
bannerPhoto: /img/brook.jpg
thumbnailPhoto: /img/brook.jpg
---
View /loader.ts para ver como isso funciona.
Basta adicionar seu ID do Google Analytics (por exemplo, 'UA-9999999999-1') aos globals.ts e Devii adicionará automaticamente o snippet apropriado do Google Analytics ao seu site. Vá para /pages/_app.ts para ver como isso funciona ou personalize esse comportamento.
O Renderer de Markdown ( Markdown.tsx ) fornece um estilo padrão inspirado no Medium. Basta modificar o CSS em Markdown.tsx para personalizar o design do seu gosto.
Você pode facilmente soltar blocos de código em suas postagens no blog usando sintaxe tripla-backtick (assim como o Github). Não é mais incorporar o codepen iframes!
Funciona imediatamente para todas as linguagens de programação. Especifique seu idioma com uma "tag de idioma". Então isso:
`` `ts
// muito legal hein?
const test = (arg: string) => {
retornar arg.length> 5;
};
`` `se transforma em
// pretty neat huh?
const test = ( arg : string ) => {
return arg . length > 5 ;
} ; View /components/Code.tsx para ver como isso funciona ou personalize esse comportamento.
Você não precisa entender tudo isso para usar o DEVII. Considere isso um "guia avançado" que você pode usar se desejar personalizar a estrutura do site.
As postagens de marcação são carregadas durante a etapa de construção estática do próximo.js. Confira a documentação de busca de dados para saber mais sobre isso.
Aqui está a versão curta: se exportar uma função chamada getStaticProps de um dos componentes da sua página, o próximo.js executará essa função, assumirá o resultado e passará a propriedade props (que deve ser outro objeto) em sua página como adereços.
Você pode carregar e analisar dinamicamente um arquivo de marcação usando loadMarkdownFile , uma função utilitária implementada no loader.ts . É uma função assíncrona que retorna um objeto TypeScript PostData que contém todas as teclas de metadados listadas acima:
Para um exemplo disso, consulte a implementação getStaticProps na página inicial. A função chama loadBlogPosts - uma função utilizada que carrega todas as postagens do blog no /md/blog/ Diretório, os analisa e retorna PostData[] .
export const getStaticProps = async ( ) => {
const posts = await loadBlogPosts ( ) ;
return { props : { posts } } ;
} ; Existem algumas funções de utilidade no loader.ts que o DEVII usa. Todas as funções são assíncronas ! Todas as funções aceitam um caminho relativo que deve ser _Relativo para o md/ Diretório. Por exemplo loadPost('blog/test.md' ) carregaria /md/blog/test.md .
loadPost carrega/analisa um arquivo de marcação e retorna um PostDataloadBlogPosts : Carrega/analisa todos os arquivos em /md/blog/ . Retorna PostData[] . Usado em index.tsx para carregar/renderizar uma lista de todas as postagens de blog publicadasloadMarkdownFile : carrega um arquivo de marcação, mas não o analisa. Retorna o conteúdo da string. Útil se você deseja implementar algumas partes de uma página em Markdown e outras peças no ReactloadMarkdownFiles : aceita um padrão glob e carrega todos os arquivos dentro /md/ cujos nomes correspondem ao padrão. Usado internamente por loadBlogPosts Você pode gerar uma versão totalmente estática do seu site usando yarn build && yarn export . Esta etapa é totalmente alimentada por Next.JS. O local estático é exportado para o diretório out .
Depois de gerado, use seu serviço de hospedagem de arquivos estáticos de escolha (vercel, netlify, Firebase Hosting, Amazon S3) para implantar seu site.
Existe um arquivo globals.ts na raiz do projeto que contém algumas configurações/metadados de configuração sobre o seu site:
yourName : seu nome, usado para as tags de direitos autorais no rodapé e no feed RSS, por exemplo, Alyssa P. HackersiteName : o título do seu blog, por exemplo, Alyssa's Cool Blog ;siteDescription : Uma descrição curta, usada na tag meta descrição, por exemplo, 'eu escrevo sobre o código' n stuff ';siteCreationDate : usado no feed RSS gerado. Use este formato: '3 de março de 2020 04:00:00 GMT';twitterHandle : o identificador do Twitter para você ou seu blog/empresa, usado nas metatags do Twitter. Inclua o símbolo @, por exemplo, '@alyssaphacker';email : seu e -mail, usado como o campo "Webmaster" e "GerenteDeditor" do feed RSS gerado, por exemplo, [email protected] ;url : o URL base do seu site, usado para "calcular" links canônicos padrão de caminhos relativos, por exemplo, 'https://alyssaphacker.com';accentColor : a cor de fundo do cabeçalho e do rodapé, por exemplo, #4fc2b4 ; Um feed RSS é gerado automaticamente no seu feed de postagem no blog. Este feed é gerado usando o módulo rss (para converter o formato JSON em RSS) e showdown para converter os arquivos de marcação em HTML compatível com RSS.
Para que a geração de RSS funcione, todas as suas postagens devem conter um registro datePublished e hora publicados em seus metadados frontmatter. Para examinar ou personalizar a geração RSS, consulte o arquivo rssUtil.ts no diretório raiz.
Cada página de postagem do blog preencheu automaticamente as tags com base nos metadados do post. Isso inclui uma tag title , meta , og: tags, metadados do Twitter e uma tag link que contém o URL canônico.
O valor padrão do URL canônico é calculado concatenando o valor da sua configuração url (consulte as configurações globais acima) e o caminho relativo da sua postagem. Verifique se o URL canônico é exatamente equivalente ao URL no navegador ao visitar seu site ao vivo, caso contrário, o SEO do seu site pode sofrer.
Não há nada "Under the Hood" aqui. Você pode visualizar e modificar todos os arquivos que fornecem a funcionalidade listada acima. O DEVII apenas fornece um andaime do projeto, alguns utilitários de carregamento de carregamento de marcação (no loader.ts ) e alguns padrões sensatos de estilo (especialmente em Markdown.tsx ).
Para começar a personalizar, consulte o código -fonte do index.tsx (a página inicial), BlogPost.tsx (o modelo de postagem do blog) e Markdown.tsx (o renderizador do Markdown).
Vá ao repositório do Github para começar: https://github.com/colinhacks/devii. Se você gosta deste projeto, deixe uma ️star️ para ajudar mais pessoas a encontrar Devii?
yarn dev Inicia o servidor de desenvolvimento. Equivalente ao next dev .
yarn build Cria uma construção otimizada do seu site. Equivalente à next build .
yarn export Exporta seu site para arquivos estáticos. Todos os arquivos são gravados para /out . Use seu serviço de hospedagem de arquivos estáticos de escolha (Hosting Firebase, Amazon S3, Vercel) para implantar seu site. Equivalente à next export .
