![]() ![]() Writing technical articles becomes fun, if you can use the tools and languages you love. Pandoc is also able to read the include statements for partial markdown files I mentioned earlier. It’s also possible to use custom themes, to ensure that your articles either follow a given corporate identity or reuse your preferred fonts, colors, margins, … Generating previews and deliverablesįor generating previews or deliverables, I use either the export function offered by iA Writer or Pandoc. In these days I prefer iA Writer, it’s easy to use and it supports embedding partial markdown files □□. You should never stop looking for new opportunities or alternatives to things you currently use. I’m always trying to find better tooling. Last, but not least I have dedicated folders for previews and deliverables, those folders normally contain generated PDF version of the article. Otherwise, I’ve to move around three lines (two lines with the three back-ticks and the include statement). Having this format, I can copy, cut and paste just the single line to include that particular snippet in the text. Each snippet starts with three back-ticks and also end with those. The advantage of putting the snippet itself, again into a markdown file is just laziness. ![]() Yes, I write all my snippets in markdown instead of just putting a raw code file there. Images, surprisingly remain to the images subfolder and to stay consistent, all code snippets (longer than three lines) are stored as dedicated markdown files inside of snippets. Some artifacts are always pre-populated like 001-intro.md and 999-outro.md. I break my article into small chunks and arrange those chunks in super-awesome-article.md. The artifacts folder is a collection of small markdown files. Next, to this, I store other markdown files containing notes, notes I use during the early stages when I need to do some research on a topic I’ve to cover as part of the article. The main article file super-awesome-article.md is, of course, the most important one. articles/recent-article/artefacts/snippets/001-hello-world.js.mdįirst, there is the main article folder (here recent-article). articles/recent-article/artefacts/snippets/ articles/recent-article/artefacts/images/001-fx-architecture.png articles/recent-article/artefacts/images/ articles/recent-article/artefacts/999-outro.md articles/recent-article/artefacts/000-intro.md articles/recent-article/super-awesome-article.md But this reference has to be placed in its own row. ![]() You just provide the path for the markdown file you want to include and you’re done. But that’s where tooling comes into play.Ī lot of writing tools like iA Writer are supporting exactly this feature. Unfortunately, this isn’t supported by the current Markdown standard out of the box. Because technical articles grow fast, I wanted to be able to split articles into separate markdown files. ![]() Markdown offers everything I need to produce technical articles. So I could easily access any final article later using GitHub’s website and I don’t have to browse thru the repositories history. If you assign a tag to a commit in git, it becomes a release on GitHub. I merge to master once I’ve finished an article and associate a proper w to the merge commit. I ended up in just working on my develop branch. In the beginning, I was also using git flow and created dedicated feature branches for every article. Books are too big, and perhaps you want to set up webhooks to automatically generated previews for your book on each and every push. Only books, for every book I wrote, a dedicated repository has been created. I’ve created dedicated repositories for all different kind of publications (print articles, online articles, white papers). I use GitHub and their $7 paid plan to create as many private repositories I want to. Of course are all my articles stored in a private repository. git makes editing, restoring and merging various parts of an article very easy.Įverything I create is under version control, so why should my articles be the only exception? Of course, do you need all the regular support for images, footnotes, and so on.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |