devii
v0.5.0
Un démarreur de blog de développeur pour 2020.
Next.js
Réagir
Manuscrit
Réduction
Syntaxe mise en évidence
Référencement
Génération RSS
Si vous êtes heureux et que vous le savez, jouez ce repo
/md/blogMarkdown.tsx avec la prise en charge de la syntaxe de style GitHub mettant en évidenceEn savoir plus sur la motivation + le design derrière Devii sur https://colinhacks.com/blog/devii.
Ce dépôt contient le code pour https://devii.dev.
Devii.dev sert à la fois de documentation et d'une démonstration de travail de Devii. Après l'avoir cloné / fourre-le, vous pouvez parcourir le code pour savoir comment fonctionne Devii. Ensuite, vous pouvez arracher tout ce que vous n'aimez pas, personnaliser tout le reste et créer vos propres outils et composants en plus de la fondation que Devii fournit!
Votre site Web personnel est la manifestation en ligne de vous. Devii ne fournit pas vraiment grand-chose de la boîte. Il fournit de beaux styles par défaut de style moyen pour vos articles de blog et quelques outils pour le chargement / le rendu. Mais vous devrez implémenter plus ou moins votre propre page d'accueil à partir de zéro. Et c'est le point! Ne vous contentez pas d'un thème. Construire quelque chose qui vous représente.
Pour commencer:
git clone [email protected]:yourusername/devii.git my-blog
cd my-blog
yarn
yarn dev . Cela devrait démarrer un serveur sur http://localhost:3000 . Le cœur de ce dépôt est suivant.js. Nous avons choisi Next.js car c'est le moyen le plus simple et le plus élégant de générer une version statique d'un site Web basé sur React. La documentation est excellente; Lisez-le d'abord: Documentation Next.js.
Voici une version abrégée de la structure du projet. Certains fichiers de configuration ( next.config.js , next-end.d.ts , .gitignore ) ont été supprimés pour simplicité.
.
├── 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 génère une nouvelle page Web pour chaque fichier dans le répertoire pages . Si vous souhaitez ajouter une page à propos de votre blog, ajoutez simplement about.tsx à l'intérieur pages et commencez à écrire la page.
Par défaut, le repo contient uniquement deux pages: une page d'accueil ( /pages/index.tsx ) et une page de blog ( /pages/[blog].md blog
Le fichier [blog].ts suit la convention suivante.js de l'utilisation des crochets pour indiquer un itinéraire dynamique.
La page d'accueil est intentionnellement minime. Vous pouvez mettre ce que vous voulez dans index.tsx ; L'un de nos objectifs dans la conception de Devii a été de ne imposer aucune restriction au développeur. Utilisez votre imagination! Votre site Web est la manifestion en ligne de vous. Vous pouvez utiliser tous les packages NPM ou les bibliothèques de style que vous aimez.
Devii n'est pas opiné sur le style. Parce que votre site Devii est une application React standard sous le capot, vous pouvez utiliser votre bibliothèque préférée de npm pour faire du style.
Devii fournit certains styles par défaut, notamment dans le rendu de Markdown ( /components/Markdown.tsx markdown.tsx). Ces styles sont implémentés à l'aide de la solution de style intégrée de Next styled-jsx . Malheureusement, il était nécessaire de rendre ces styles mondiaux, car styled-jsx ne joue pas bien avec des composants tiers (dans ce cas react-markdown ).
N'hésitez pas à réimplémenter les styles intégrés avec votre bibliothèque de choix si vous choisissez d'utiliser une bibliothèque de style séparée (l'émotion est assez glorieuse), vous pouvez réimplémenter les styles par défaut
Il suffit d'ajouter un fichier Markdown sous md/blog/ pour créer un nouvel article de blog:
foo.md dans le répertoire /md/bloghttp://localhost:3000/blog/foo . Vous devriez voir le nouveau message. Chaque fichier Markdown peut inclure un "bloc de frontmatter" contenant diverses métadonnées. Devii fournit un utilitaire loadPost qui charge un fichier Markdown, analyse les métadonnées de Frontmatter et renvoie un objet PostData structuré:
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 ;
} ; Par exemple, voici le blog Frontmatter de l'exemple de blog ( 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 pour voir comment cela fonctionne.
Il suffit d'ajouter votre identifiant Google Analytics (par exemple, UA-999999999-1 ') à globals.ts et Devii ajoutera automatiquement l'extrait Google Analytics approprié à votre site. Accédez à /pages/_app.ts pour voir comment cela fonctionne ou personnaliser ce comportement.
Le rendu de Markdown ( Markdown.tsx ) fournit un style par défaut inspiré de Medium. Modifiez simplement le CSS dans Markdown.tsx pour personnaliser la conception à votre goût.
Vous pouvez facilement déposer des blocs de code dans vos articles de blog à l'aide de la syntaxe triple dossier (tout comme GitHub). Plus d'incorporation de codepen iframes!
Fonctionne à l'extérieur de la boîte pour tous les langages de programmation. Spécifiez votre langue avec une "balise de langue". Alors ceci:
`` `ts
// assez soigné hein?
const test = (arg: string) => {
return arg.length> 5;
};
`` 'se transformer en
// pretty neat huh?
const test = ( arg : string ) => {
return arg . length > 5 ;
} ; Voir /components/Code.tsx pour voir comment cela fonctionne ou personnaliser ce comportement.
Vous n'avez pas besoin de comprendre tout cela pour utiliser Devii. Considérez ceci comme un "guide avancé" que vous pouvez utiliser si vous souhaitez personnaliser la structure du site.
Les poteaux de marquage sont chargés lors de l'étape de construction statique suivante. Consultez la documentation de récupération des données pour en savoir plus à ce sujet.
Voici la version courte: si exporter une fonction appelée getStaticProps à partir de l'un de vos composants de page, next.js exécutera cette fonction, prendra le résultat et passera la propriété props (qui devrait être un autre objet) dans votre page en tant que plongeon.
Vous pouvez charger et analyser dynamiquement un fichier Markdown à l'aide de loadMarkdownFile , une fonction utilitaire implémentée dans loader.ts . Il s'agit d'une fonction asynchrone qui renvoie un objet TypeScript PostData contenant toutes les touches de métadonnées répertoriées ci-dessus:
Pour un exemple de cela, consultez l'implémentation getStaticProps à partir de la page d'accueil. La fonction appelle loadBlogPosts - une fonction Utilty qui charge tous les articles de blog dans le /md/blog/ Directory, les analyse et renvoie PostData[] .
export const getStaticProps = async ( ) => {
const posts = await loadBlogPosts ( ) ;
return { props : { posts } } ;
} ; Il y a quelques fonctions d'utilité dans loader.ts que Devii utilise. Toutes les fonctions sont asynchrones ! Toutes les fonctions acceptent un chemin relatif qui devrait être lié à la md/ répertoire. Par exemple loadPost('blog/test.md' ) chargerait /md/blog/test.md .
loadPost charge / analyse un fichier Markdown et renvoie un PostDataloadBlogPosts : charge / analyse tous les fichiers dans /md/blog/ . Renvoie PostData[] . Utilisé dans index.tsx pour charger / rendre une liste de tous les articles de blog publiésloadMarkdownFile : charge un fichier de marque mais ne l'analyse pas. Renvoie le contenu de la chaîne. Utile si vous souhaitez implémenter certaines parties d'une page dans Markdown et d'autres pièces dans ReactloadMarkdownFiles : accepte un modèle glob et charge tous les fichiers à l'intérieur /md/ dont les noms correspondent au modèle. Utilisé en interne par loadBlogPosts Vous pouvez générer une version entièrement statique de votre site à l'aide de yarn build && yarn export . Cette étape est entièrement alimentée par Next.js. Le site statique est exporté vers le répertoire out .
Une fois généré, utilisez votre service d'hébergement de fichiers statique de choix (Vercel, Netlify, Hébergement Firebase, Amazon S3) pour déployer votre site.
Il existe un fichier globals.ts dans la racine du projet contenant certains paramètres / métadonnées de configuration sur votre site:
yourName : votre nom, utilisé pour les étiquettes du droit d'auteur dans le pied de page et le flux RSS, par exemple Alyssa P. HackersiteName : le titre de votre blog, par exemple Alyssa's Cool Blog ;siteDescription : une brève description, utilisée dans la balise meta Description, par exemple «j'écris sur le code« n trucs »;siteCreationDate : Utilisé dans le flux RSS généré. Utilisez ce format: «3 mars 2020 04:00:00 GMT»;twitterHandle : la poignée Twitter pour vous ou votre blog / entreprise, utilisée dans les balises Twitter Meta. Inclure le symbole @, par exemple '@alyssaphacker';email : votre e-mail, utilisé comme champ "webmaster" et "managediter" du flux RSS généré, par exemple [email protected] ;url : L'URL de base de votre site Web, utilisée pour «calculer» les liens canoniques par défaut à partir de chemins relatifs, par exemple «https://alyssaphacker.com»;accentColor : la couleur d'arrière-plan de l'en-tête et du pied de page, par exemple #4fc2b4 ; Un flux RSS est généré automatiquement à partir de votre flux d'articles de blog. Ce flux est généré à l'aide du module rss (pour convertir JSON au format RSS) et showdown pour convertir les fichiers de démarque en HTML compatible RSS.
Pour que RSS Generation fonctionne, tous vos messages doivent contenir un horodat datePublished dans leurs métadonnées de la masse. Pour examiner ou personnaliser la génération RSS, consultez le fichier rssUtil.ts dans le répertoire racine.
Chaque page de billet de blog a automatiquement rempli des balises de méta basées sur les métadonnées du post. Cela comprend une balise title , des tags meta , og: Tags, des métadonnées Twitter et une balise link contenant l'URL canonique.
La valeur par défaut de l'URL canonique est calculée en concaténant la valeur de votre configuration url (voir les configurations globales ci-dessus) et le chemin relatif de votre message. Vérifiez que l'URL canonique est exactement équivalente à l'URL du navigateur lors de la visite de votre site en direct, sinon le référencement de votre site peut en souffrir.
Il n'y a rien de "sous le capot" ici. Vous pouvez afficher et modifier tous les fichiers qui fournissent les fonctionnalités répertoriées ci-dessus. Devii fournit simplement un échafaudage de projet, certains utilitaires de chargement de chargement de marque (dans loader.ts ), et quelques défauts de style sensibles (en particulier dans Markdown.tsx ).
Pour commencer la personnalisation, consultez le code source d' index.tsx (la page d'accueil), BlogPost.tsx (le modèle de billet de blog) et Markdown.tsx (The Markdown Renderer).
Dirigez-vous vers le dépôt GitHub pour commencer: https://github.com/colinhacks/devii. Si vous aimez ce projet, laissez un ourdards pour aider plus de gens à trouver Devii?
yarn dev Démarre le serveur de développement. Équivalent au next dev .
yarn build Crée une construction optimisée de votre site. Équivalent à next build .
yarn export Exporte votre site vers des fichiers statiques. Tous les fichiers sont écrits à /out . Utilisez votre service d'hébergement de fichiers statique de choix (Firebase Hosting, Amazon S3, Vercel) pour déployer votre site. Équivalent à next export .
