Markdown

Markdown is a common markup language frequently used by developers to write Python project documention.

Unofficial Markdown logo.

Markdown's origin

Markdown was originally developed by John Gruber in 2004. The markup language's lightweight design helped it gain rapid adoption by software developers and designers. The format's simplicity also makes it easier to write parsers to convert the structured syntax into other formats such as HTML and JSON.

Markdown resources

Markdown does not have an extensive set of strict rules like some other text formats so you should be able to read up on the basics with these articles then write a few practice documents to be comfortable with it. The following resources are really helpful when you are getting started or need a quick reference on a less commonly-used feature such as tables or block quotes.

  • Say yes to Markdown, no to MS Word provides a really awesome overview of why Markdown is a more usable file format than Microsoft Word and similar proprietary file types. The article also has a good list of useful Markdown-related tools such as a Markdown-to-PDF converter (a NodeJS package but easy enough to use with a basic development environment).

  • Markdown syntax is the defacto standard and wonderful reading for both initial learning and random reference.

  • Markdown cheatsheet is a quick reference that is a shortened version of the above Markdown syntax page.

  • Markdown parsers in Python reviews many of the most common Python Markdown parser implementations to give insight into the advantages and disadvantages of each one.

  • reStructuredText vs Markdown for documentation brings up some really good points about the downsides to Markdown's simplicity. First, a lot of documentation needs more complex output that is not possible with vanilla Markdown so you need to drop into plain old HTML, which defeats the purpose of using a markup language. Second, some of the syntax around inserting blank lines by adding spaces at the end of lines is confusing if someone is using a text editor or development environment that is not configured to show blank spaces. Worse yet, if your editor is set to remove blank spaces at the end of lines, which is fairly common among developers, then you can mistakenly break the formatting intended by the original author. Overall this is a good piece to read for a balanced view of Markdown and the reasons it provides are one reason why I use both Markdown and reStructuredText depending on the project.

  • The Python Package Index (PyPI) supports Markdown as of 2018 although there are still some tweaks being made to the flavors that can be used such as GitHub-flavored Markdown.

What else do you want to learn?

What is a static website generator?

I want to learn how to code a Python web application using a framework.

I've built a Python web app, now how do I deploy it?

Sign up for two emails per month with Python tutorials and Full Stack Python updates.

Sponsored By

Mapbox logo.

Easily build maps, search and navigation into your Python applications with Mapbox.

Full Stack Python

Full Stack Python is an open book that explains concepts in plain language and provides helpful resources for those topics.
Updates via newsletter, Twitter & Facebook.
1. IntroductionLearning ProgrammingCore LanguageWhy Use Python?Python 2 or 3?Enterprise PythonPython CommunityCompanies using PythonBest Python ResourcesBest Python VideosBest Python Podcasts2. Development EnvironmentsText Editors & IDEsVimEmacsSublime TextPyCharmJupyter NotebookShellsBash shellZshPowerShellTerminal MultiplexerstmuxScreenPymuxEnvironment configurationApplication DependenciesVirtualenvsEnvironment variablesLocalhost tunnelsSource ControlGitMercurialApache SubversionHosted Source ControlGitHubBitBucketGitLab3. DataRelational DatabasesPostgreSQLMySQLSQLiteObject-relational MappersSQLAlchemyPeeweeDjango ORMSQLObjectPony ORMNoSQL Data StoresRedisMongoDBApache CassandraNeo4jData analysispandasNumPySciPyBokehd3.jsMatplotlibMarkdown4. Web DevelopmentWeb FrameworksDjangoFlaskBottlePyramidFalconMorepathSanicOther Web FrameworksTemplate EnginesJinja2MakoDjango TemplatesWeb DesignHTMLCascading Style Sheets (CSS)Responsive DesignMinificationCSS FrameworksBootstrapFoundationJavaScriptTask QueuesCeleryRedis Queue (RQ)DramatiqStatic Site GeneratorsPelicanLektorMkDocsTestingUnit TestingIntegration TestingCode MetricsDebuggingWebSocketsuvloopWeb APIsMicroservicesBotsAPI CreationAPI IntegrationTwilioSecurity5. DeploymentServersStatic ContentVirtual Private ServersPlatform-as-a-ServiceOperating SystemsUbuntuWeb ServersApache HTTP ServerNginxCaddyWSGI ServersGreen Unicorn (Gunicorn)Continuous IntegrationJenkinsConfiguration ManagementAnsibleDockerServerlessAWS LambdaGoogle Cloud Functions6. DevOpsMonitoringRollbarCachingLoggingWeb AnalyticsChange LogWhat Full Stack MeansAbout the AuthorFuture DirectionsPage Statuses ...or view all topics.

Matt Makai 2012-2018