Pocket Science Lab

The PSLab Android App and the PSLab Desktop App come with built-in experiments which include the experiment setups as well as the experiment docs. The experiment docs for PSLab have been written in the Markdown format. So, the markdown support had to be enabled in the PSLab Android App. There are numerous markdown file renderers for android. The most popular among them is MarkdownView (https://github.com/falnatsheh/MarkdownView) which is an  open-source service. This blog covers how to enable the support for markdown in apps and use to generate elegant documentation. Enabling MarkdownView MarkdownView can be enabled by simply adding a dependency in the build.gradle file compile 'us.feras.mdv:markdownview:1.1.0'   Creating the layout file The layout file for supporting a markdown file is fairly simple. The inclusion of the above dependency simplifies the things. The view holder for markdown is created and an id is assigned to it. <?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent"> <br.tiagohm.markdownview.MarkdownView android:layout_width="match_parent" app:escapeHtml="false" android:layout_height="match_parent" android:id="@+id/perform_experiment_md" /> </LinearLayout>   Loading the markdown file In order to load the markdown file, a MarkdownView object is created. Since, in the PSLab Android app, markdown files which form the documentation part are a part of the experiments. So, the files are displayed in the documentation fragment of the experiments. private String mdFile; private MarkdownView mMarkdownView; public static ExperimentDocFragment newInstance(String mdFile) { ExperimentDocFragment experimentDocFragment = new ExperimentDocFragment(); experimentDocFragment.mdFile = mdFile; return experimentDocFragment; }   The MarkdownView object created is assigned to markdown viewholder of the relevant layout file. Here, the layout file was named experiment_doc_md and the view holder was assigned the id perform_experiment_md. The markdown files were stored in the assets directory of the app and the files were loaded from the there. public View onCreateView(LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) { View view = inflater.inflate(R.layout.experiment_doc_md, container, false); mMarkdownView = (MarkdownView) view.findViewById(R.id.perform_experiment_md); mMarkdownView.loadMarkdownFromAsset("capacitance.md"); return view; }   The available methods in markdown view are loadMarkdown - loads directly from the content in the string  mMarkdownView.loadMarkdown("**MarkdownView**");   loadMarkdownFromAsset - loads markdown files located in the assets directory of the app mMarkdownView.loadMarkdownFromAsset("markdown1.md");   loadMarkdownFromFile - loads markdown from a file stored in the app not present in the assets directory mMarkdownView.loadMarkdownFromFile(new File());   loadMarkdownFromUrl - loads markdown from the specified URL (requires internet connection, as file is loaded from the web) mMarkdownView.loadMarkdownFromUrl("url");   Important points for consideration Avoid using elements of GitHub Flavoured Markdown (GFM) as it is not fully supported. It is better to stick to the traditional markdown style. While adding images in the markdown files, avoid using specific dimensions as the images may not load properly in some cases due to the wide variety of screen sizes in android devices. It is better to store the Markdown files to be loaded in the assets directory of the app and load it from there instead of the other methods mentioned above. References A comprehensive markdown tutorial to learn markdown scripting https://www.markdowntutorial.com/ MarkdownView repository on Github by tiagohm https://github.com/tiagohm/MarkdownView Learn more about Github Flavoured Markdown (GFM) https://guides.github.com/features/mastering-markdown/